部署与预览

• 1: 使用 Amazon S3 和 CloudFront 部署
• 2: 部署到 GitHub Pages
• 3: 部署到 Netlify
• 4: 在本地运行站点
• 5: 页面外壳

hugo -e development

1 - 使用 Amazon S3 和 CloudFront 部署

通过 Amazon Web Services 发布网站有多种方案。本节介绍最基础的一种：把站点部署到 S3 存储桶，并启用 CloudFront CDN（内容分发网络）来加速已部署内容的传输。

1. 完成 AWS 注册后，创建 S3 存储桶，将其关联到你的域名，再加入 CloudFront CDN。可以参考这篇博客文章，其中包含完整流程和易于操作的分步说明。

2. 下载并安装最新版 AWS 命令行界面（CLI）v2。随后运行 aws configure 配置 CLI 实例（请提前准备 AWS Access Key ID 和 AWS Secret Access Key）：

   $ 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]:
   

3. 运行 aws s3 ls 检查 AWS CLI 配置是否正确；命令应输出你的 S3 存储桶列表。

1. 在 hugo.toml、hugo.yaml 或 hugo.json 中添加如下 [deployment] 分区：

   • 配置文件：
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [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"
         }
       ]
     }
   }

1. 运行 hugo --gc --minify，将站点资源渲染到 Hugo 构建环境的 public/ 目录。

2. 使用 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 缓存失效。

3. 至此全部完成。今后只需使用 Hugo 内置的 deploy 命令，即可轻松部署到 S3 存储桶。

有关 Hugo deploy 命令及其命令行参数的更多信息，请参阅命令概览。其中，--maxDeletes int 和强制上传所有文件的 --force 参数可能会很有用。

如果 S3 无法满足需求，可以考虑 AWS Amplify Console。这是更高级的持续部署（CD）平台，内置对 Hugo 静态站点生成器的支持。Hugo 官方文档提供了相应的入门指南。

2 - 部署到 GitHub Pages

如果源码托管在 GitHub，只需一份 Actions 工作流，就能通过 GitHub Pages 构建并发布站点。消费站点需要 Hugo Extended，但不需要 Node.js、npm、PostCSS，也不需要生成专门的部署分支。

项目站点的 URL 形如 https://<OWNER>.github.io/<REPOSITORY>/；用户和组织站点使用 https://<OWNER>.github.io/。GitHub Pages 也支持自定义域名。

准备代码仓库

把完整的站点源码推送到 GitHub，并确认在仓库根目录执行以下命令能够成功：

hugo --gc --minify

将站点的 baseURL 设为生产 URL，或者在工作流中通过 Hugo 的 --baseURL 参数传入 Pages URL。项目站点必须包含仓库路径，否则 CSS、JavaScript 和其他资源会从错误的位置解析。

添加 Pages 工作流

创建 .github/workflows/pages.yml，内容如下。请让 HUGO_VERSION 始终与主题已经验证的版本保持一致。

name: Deploy Hugo site to Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

env:
  GO_VERSION: 1.25.5
  HUGO_VERSION: 0.164.0

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          submodules: recursive
      - uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
      - name: Install Hugo Extended
        run: |
          curl -L -o hugo.deb \
            "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb"
          sudo dpkg -i hugo.deb
      - uses: actions/configure-pages@v6
        id: pages
      - name: Build
        run: >-
          hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
      - uses: actions/upload-pages-artifact@v5
        with:
          path: public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

如果通过 Git submodule 安装主题，submodules: recursive 会在 Hugo 运行前检出主题。如果使用完整离线归档，则可以把相邻的 theme/ 目录提交到仓库，或在构建输入中恢复该目录。

启用 GitHub Pages

在仓库设置中打开 Pages。在 Build and deployment 下，将 Source 设为 GitHub Actions。把工作流推送到 main，然后在仓库的 Actions 标签页中查看第一次运行。

工作流只上传生成的 public/ 目录，并通过 Pages 部署 API 发布，不会维护 gh-pages 分支。

有关其他身份验证、域名和权限选项，请参阅 GitHub 的 Pages 文档和 Hugo 的 GitHub 托管指南。

3 - 部署到 Netlify

Netlify 可以从 GitHub、GitLab 或 Bitbucket 构建站点，并为每个拉取请求发布预览。OINK 消费端会直接运行 Hugo Extended，不安装 Node.js 软件包，也不调用 PostCSS。

配置站点

把完整源码推送到 Git 服务商，在 Netlify 中导入仓库，然后使用以下构建设置：

如果 Netlify 检测到仅供主题维护工具使用的软件包清单，请为站点关闭自动依赖安装。这些工具不属于消费端构建合同。

如果通过 Git submodule 安装主题，请启用递归 submodule 检出。如果使用 Hugo 模块，Netlify 还需要具备普通的 Git 和 Go 访问能力，以便在全新构建中下载已经固定版本的模块。完整离线发行包使用相邻的 theme/ 目录，可避免首次构建时下载依赖。

将配置保存在仓库中

也可以把同样的设置写入 netlify.toml 并提交：

[build]
command = "hugo --gc --minify"
publish = "public"

[build.environment]
HUGO_VERSION = "0.164.0"

除非预览环境专门用于测试升级，否则生产环境和部署预览应使用同一个 Hugo 版本。如果预览构建需要把自动生成的 URL 作为 base URL，请在对应环境的 Hugo 命令中加入 Netlify 部署 URL。

如果不希望非生产部署被索引，请按照构建环境与索引中的说明使用非生产 Hugo 环境。

保存设置后触发一次部署，并检查构建日志。正常的消费端构建应该只出现一条 Hugo 命令，不应运行 npm、PostCSS、Autoprefixer、CDN 下载或构建期远程资源步骤。

4 - 在本地运行站点

根据所选部署方式，你可能需要在开发期间于本地运行站点，以便预览内容变更。具体步骤如下：

1. 确认已经从代码仓库克隆站点文件，并将本地副本更新至最新状态。

2. 按照前提条件与安装中的说明，安装 Hugo Extended，以及所选主题安装方式获取源码时需要的工具。Node.js 和 PostCSS 不是站点构建的前提条件。

3. 在站点根目录运行 hugo server。默认情况下，可以通过 http://localhost:1313 访问站点。

站点在本地运行后，Hugo 会监视内容变更并自动刷新页面。如果本地有多个 Git 分支，切换分支后，本地站点也会随之反映当前分支中的文件。

5 - 页面外壳

主题会在每个适用页面中完整渲染顶部导航栏、侧栏、目录、搜索入口和页脚。无论是常规构建、预览、离线归档、搜索爬虫，还是不运行 JavaScript 的客户端，这都是唯一且规范的生产结构。

本主题不包含上游实验性的 td.chrome = shared 供体/恢复模式。params.td.chrome 设置不会产生任何效果，迁移站点时应将其删除。只保留一套服务端渲染结构，可以避免出现第二套视觉实现，并让导航、语言选择、无障碍语义和离线行为保持确定。

请使用 Hugo 压缩和托管层压缩来减少传输体积：

hugo --gc --minify

交互式外壳脚本只会增强已经渲染的标记，不负责重建缺失的导航区域。