部署与预览 on OINK 文档主题

使用 Amazon S3 和 CloudFront 部署

Mon, 01 Jan 0001 00:00:00 +0000

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

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

下载并安装最新版 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]:

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

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

部署到 GitHub Pages

Mon, 01 Jan 0001 00:00:00 +0000

如果源码托管在 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/ 目录提交到仓库，或在构建输入中恢复该目录。

部署到 Netlify

Mon, 01 Jan 0001 00:00:00 +0000

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

配置站点

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

设置	值
构建命令	`hugo --gc --minify`
发布目录	`public`
`HUGO_VERSION`	`0.164.0` 或主题验证过的其他版本

如果 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。

在本地运行站点

Mon, 01 Jan 0001 00:00:00 +0000

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

确认已经从代码仓库克隆站点文件，并将本地副本更新至最新状态。
按照前提条件与安装中的说明，安装 Hugo Extended，以及所选主题安装方式获取源码时需要的工具。Node.js 和 PostCSS 不是站点构建的前提条件。
在站点根目录运行 hugo server。默认情况下，可以通过 http://localhost:1313 访问站点。

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

页面外壳

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

hugo --gc --minify

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