预览和部署

Version main of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

预览和部署

部署你的Docsy站点

有多种可能的选项可用于部署 Hugo 站点，包括 Netlify、Firebase Hosting、带有 Aerobatic 的 Bitbucket 等等；您可以在 Hosting and Deployment中了解所有这些选项。Hugo 也可以轻松地在本地部署站点，以快速预览内容。

本地服务您的站点

根据您的部署选择，您可能希望在开发过程中本地服务您的站点以预览内容更改。要本地服务您的站点：

确保您从存储库克隆了最新的本地站点文件副本。
确保您在本地计算机上安装了Prerequisites and installation 中描述的工具，包括 postcss-cli（您需要它来在第一次运行服务器时生成站点资源）。
在站点根目录中运行 hugo server 命令。默认情况下，您的站点将在 http://localhost:1313 上可用。

现在您正在本地服务站点，Hugo 将监视内容更改并自动刷新您的站点。如果您有多个本地 git 分支，则在切换 git 分支时，本地站点将反映当前分支中的文件。

构建环境和索引

默认情况下，使用hugo构建（而不是在本地使用hugo server）的Hugo站点具有Hugo构建环境production。使用production构建的Docsy站点可以被搜索引擎索引，包括Google定制搜索引擎。生产构建还为现场部署优化了JavaScript和CSS（例如，使用压缩后的JS而不是更易读的原始源）。

如果您不希望搜索引擎索引您的部署站点（例如，如果您仍在开发您的实时站点），或者如果您想构建用于离线分析的开发版本的站点，可以将Hugo构建环境设置为其他环境名称，例如development（在本地使用hugo server的默认设置），test或您选择的另一个环境名称。

设置的最简单方法是在指定或运行hugo命令时使用-e标志，如以下示例所示：

hugo -e development

使用 Netlify 部署

我们推荐使用Netlify作为一种特别简单的方法，从您的Git提供程序（GitHub、GitLab或BitBucket）提供您的站点，具有持续部署，在您或您的用户针对文档存储库创建拉取请求时生成的站点预览等功能。对于开源项目，Netlify是免费的，如果您需要更多支持，则有高级版。

在使用 Netlify 部署之前，请确保按照使用主题中的任何设置说明，将您的站点源代码推送到您选择的 GitHub（或其他提供者）仓库。

然后按照在 Netlify 上托管中的说明设置 Netlify 帐户（如果您还没有帐户），并授权访问您的 GitHub 或其他 Git 提供者帐户。登录后：

单击“从 Git 新建站点”。
单击所选的 Git 提供程序，然后从存储库列表中选择站点存储库。
在“部署设置”页面中：
1. 指定 Build 命令。确切的构建命令取决于您选择如何使用 Docsy：
  - 如果你使用 Docsy 作为 [Git 子模块]（/docs/get-started/other-options/#option-1-docsy-as-a-git-submodule），请指定 ‘cd themes/docsy && git submodule update -f –init && cd ../..&&雨果’。您需要指定它而不仅仅是“hugo”，以便 Netlify 可以使用主题的子模块。
  - 如果你将 Docsy 用作 [Hugo 模块]（/docs/get-started/docsy-as-module/）或 NPM 包，你可以只指定 ‘hugo’。
单击“显示高级”。
在“高级生成设置”部分中，单击“新建变量”。
指定 ‘NODE_VERSION’ 作为新变量的 Key，并将其 Value 设置为 node.js 的 [最新 LTS 版本]（https://nodejs.org/en/download/）（最低推荐版本：‘v20.x’）。
在“高级构建设置”部分中，单击“新建变量”。
指定 ‘HUGO_VERSION’ 作为新变量的 Key，并将其 Value 设置为 Hugo 的 [最新版本]（https://github.com/gohugoio/hugo/releases）（最低推荐版本：‘0.125.4’）。
在“高级生成设置”部分中，再次单击“新建变量”。
指定 ‘GO_VERSION’ 作为新变量的 Key，并将其 Value 设置为 Go 的 [最新版本]（https://go.dev/dl/）（最低推荐版本：‘1.21’）。

如果您不希望您的网站被搜索引擎索引，您可以在构建命令中添加环境标志以指定非“生产”环境，如 [构建环境和索引]（#build-environments-and-indexing）中所述。

单击“部署站点”。

Note

Netlify 在构建站点之前使用站点仓库的 package.json 文件来安装任何 JavaScript 依赖项（如 postcss）。如果您没有仅仅复制我们示例站点的此文件版本，请确保您已指定了我们所有的先决条件。

例如，如果您想使用高于 8.0.0 版本的 postcss-cli 版本，则需要确保您的 package.json 文件还单独指定了 postcss：

"devDependencies": {
"autoprefixer": "^9.8.8",
"postcss-cli": "^8.0.0",
"postcss": "^8.0.0"
}

或者，您可以按照相同的说明，但在您的仓库中的 netlify.toml 文件中指定您的部署设置，而不是在 部署设置 页面中指定。您可以在 Docsy 主题仓库中看到一个示例（尽管请注意，此处的构建命令有点不寻常，因为 Docsy 用户指南在本主题仓库内部）。

如果您已有一个现有的部署，您可以通过在Netlify的站点列表中选择该站点，然后点击Site settings - Build and deploy来查看和更新相关信息。请确保在Build image selection章节中选择了Ubuntu Xenial 16.04 - 如果您正在创建新的部署，则默认使用此镜像。您需要使用此镜像来运行Hugo的扩展版本。

GitHub Pages 上的部署

如果您的存储库托管在 [GitHub]（https://github.com）上，一个简单的选项是使用 [GitHub Pages]（https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages）为您的站点提供服务。GitHub Pages 允许您创建项目、用户和组织网站;对于项目网站，您的网站 URL 将为“http（s）：//.<repository_name>github.io/”，还支持自定义域。GitHub Pages 附带使用 GitHub 操作的 [持续部署]（https://docs.github.com/en/actions/deployment/about-deployments/about-continuous-deployment），而 [操作市场]（https://github.com/marketplace/actions）具有用于拼写和链接检查、部署预览等的有用工具。使用现有的 GitHub 帐户，您可以首先使用公开可用存储库的免费计划，并为业务用例提供高级套餐。

Docsy 示例站点存储库提供了一个 [工作流文件]（https://github.com/google/docsy-example/blob/master/.github/workflows/deploy-github-pages.yml），您可以在部署到 GitHub Pages 时使用。如果您使用示例网站作为新网站的模板，如 [此处]（https://www.docsy.dev/docs/get-started/docsy-as-module/example-site-as-template/）所述，则存储库中可能已经有此文件，如果没有，下面的说明将向您展示如何创建自己的工作流文件。

在 GitHub Pages 上部署之前，请确保已按照 [使用主题]（/docs/get-started/docsy-as-module）中的任何设置说明将站点源推送到所选的 GitHub 存储库。

Correct baseURL setting

确保通过 hugo 的 ‘–baseURL ‘…’’ 命令行参数或在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 配置文件中正确设置您网站的 ‘baseURL’。部署到 GitHub 页面时，需要将“baseURL”设置为“https://.github.io/<repository_name>”，否则站点布局将被破坏。

使用 GitHub Pages，默认情况下，网站将发布到分支“gh-pages”并从那里提供。必须先在 GitHub Web 界面中或通过命令行（在本地存储库克隆的根目录下）创建此分支：
```
$ git checkout -b gh-pages
Switched to a new branch 'gh-pages'
```

将此本地分支推送到您的存储库：

$ git push --set-upstream origin gh-pages
 details omitted …
 * [new branch]      new -> new
branch 'gh-pages' set up to track 'origin/gh-pages'.

切换回存储库的“main”（或“work”）分支：
```
$ git checkout main
Switched to branch 'main'
```

检查您的存储库中是否已有工作流文件“.github/workflows/deploy-github-pages.yml”。如果此文件不存在，请执行以下操作：

从存储库的根目录创建新的空工作流文件，如下所示：

mkdir -p .github/workflows
touch .github/workflows/deploy-github-pages.yml

在您选择的编辑器中打开文件，粘贴下面的代码，然后保存文件：

name: Deployment to GitHub Pages

on:
  workflow_dispatch:
  push:
    branches:
      - main  # <-- specify the branch you want to deploy from
  pull_request:

env:
  REPO_NAME: ${{ github.event.repository.name }}
  REPO_OWNER: ${{ github.repository_owner }}

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.125.5'
          extended: true

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: '**/package-lock.json'

      - run: npm ci
      - run: hugo --baseURL https://${REPO_OWNER}.github.io/${REPO_NAME} --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }} # <-- specify same branch as above here
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

将文件添加到暂存区域，提交更改并将更改推送到远程 GitHub 存储库：

git add .github/workflows/deploy-github-pages.yml
git commit -m "Adding workflow file for site deployment"
git push origin

在浏览器中，确保您已登录 GitHub 帐户。在存储库“设置”中，选择“页面”。
1. 在“生成和部署”下，在“源”下拉列表中选择“从分支部署”。
2. 从“分支”下拉列表中，选择“gh-page”作为构建站点的分支。
3. 从“文件夹”下拉列表中，选择“/（root）”作为根目录。

就是这样！已配置站点的部署工作流。

现在，将来对工作流文件中指定的分支的任何推送都将触发工作流文件中定义的操作工作流。此外，还可以使用 GitHub Web UI 手动触发部署。

推送到存储库后，可以在 GitHub Web UI 的“操作”选项卡中看到触发的工作流的进度：

URL 'Repo actions': https://github.com/<username>/<repository_name>/actions

第一次成功部署后，新环境“github-pages”将添加到您的存储库中。这显示在存储库主视图的右侧（在“版本”和“包”下方）。单击此环境时，将显示部署列表：

URL 'Repo deployments': https://github.com/<username>/<repository_name>/deployments/

您可以在 Hugo 文档的 [Hosting on GitHub]（ https://gohugo.io/hosting-and-deployment/hosting-on-github/）中找到更多信息。

对于高级用例，工作流文件中使用的 [‘hugo-action’]（https://github.com/peaceiris/actions-hugo）具有更多配置选项，这些选项都有很好的 [文档]（https://github.com/marketplace/actions/hugo-setup）。

使用Amazon S3 + Amazon CloudFront进行部署

使用 Amazon Web Services 发布您的站点有几个选项，如这篇博客文章所述。本节介绍最基本的选项，即使用 S3 存储桶部署您的站点，并激活 CloudFront CDN（内容分发网络）以加速部署内容的传递。

在您在AWS上注册之后，创建您的S3存储桶，将其与您的域名连接，并将其添加到CloudFront CDN中。这篇博客文章提供了所有细节，并为整个过程提供了易于遵循的逐步说明。

下载并安装最新版本2的AWS命令行界面(CLI)。然后通过发出命令aws configure来配置您的CLI实例(确保您随时掌握您的AWS访问密钥ID和AWS秘密访问密钥)：

$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: eu-central-1
Default output format [None]:

通过发出命令aws s3 ls检查您的AWS CLI的正确配置，这应该输出您的S3存储桶列表。

在您的hugo.toml/hugo.yaml/hugo.json中添加一个像这样的[deployment]部分：

[deployment]
[[deployment.targets]]
name = "aws"
URL = "s3://www.your-domain.tld"
cloudFrontDistributionID = "E9RZ8T1EXAMPLEID"

deployment:
  targets:
    * name: aws
      URL: 's3://www.your-domain.tld'
      cloudFrontDistributionID: E9RZ8T1EXAMPLEID

{
  "deployment": {
    "targets": [
      {
        "name": "aws",
        "URL": "s3://www.your-domain.tld",
        "cloudFrontDistributionID": "E9RZ8T1EXAMPLEID"
      }
    ]
  }
}

运行命令hugo --gc --minify将站点资产渲染到您的Hugo构建环境的public/目录中。

使用Hugo内置的deploy命令将站点部署到S3：

hugo deploy
Deploying to target "aws" (www.your-domain.tld)
Identified 77 file(s) to upload, totaling 5.3 MB, and 0 file(s) to delete.
Success!
Invalidating CloudFront CDN...
Success!

正如您所看到的，发出hugo deploy命令会自动使CloudFront CDN缓存失效。

这就是您需要做的全部！从现在开始，您可以使用Hugo内置的deploy命令轻松地将站点部署到S3存储桶！

有关Hugo deploy命令的更多信息，包括命令行选项，请参见此synopsis。特别是，您可能会发现--maxDeletes int选项或--force选项(强制上传所有文件)非常有用。

使用 GitHub actions 自动化部署

Automated deployment with GitHub actions

如果您的站点源代码存储在GitHub存储库中，您可以使用GitHub Actions在将更改提交到GitHub存储库时将站点部署到您的S3存储桶。此工作流程的设置在此博客文章中有描述。

Handling aliases

处理别名如果您使用别名进行URL管理，则应查看这篇博客文章。它解释了如何在使用Amazon S3时将别名转换为正确的301重定向。

如果S3不能满足您的需求，请考虑使用AWS Amplify Console。这是一个更先进的持续部署（CD）平台，内置支持Hugo静态网站生成器。在Hugo的官方文档中可以找到一个入门指南。

反馈

当前页面对你有帮助吗？

Glad to hear it!

Sorry to hear that. Please tell us how we can improve.

最后修改 July 6, 2024: Update _index.md (b3cce4a)