部署 on OINK

部署到 Cloudflare Pages

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

Cloudflare Pages 可以从关联的 GitHub 或 GitLab 仓库构建 Oink 站点，并为评审分支创建预览部署。消费端直接运行 Hugo Extended，无需安装前端软件包。

配置项目

在 Workers & Pages 中导入仓库，选择生产分支，并使用以下设置：

设置	值
生产分支	`main`，或经过评审的源码分支
构建命令	`hugo --gc --minify`
构建输出目录	`public`
`HUGO_VERSION`	`0.164.0`
`SKIP_DEPENDENCY_INSTALL`	`1`

请在 Production 与 Preview 环境中都设置 HUGO_VERSION。Cloudflare Pages 的 v3 构建镜像当前默认使用 Hugo 0.147.7，低于 Oink 要求的最低版本 0.160.1。固定已经验证的版本，可以避免构建镜像更新时静默改变工具链。SKIP_DEPENDENCY_INSTALL=1 会禁用 Oink 消费端不需要的通用依赖安装步骤。

如果 Hugo 站点不在仓库根目录，请把 Root directory 设置为站点目录。输出目录相对于这个根目录解析。

设置 base URL

生产构建应在 baseURL 中使用站点的规范自定义域名。如果预览需要在 canonical 与绝对链接中使用自动生成的 Pages URL，可以运行：

BASH

hugo --gc --minify --baseURL "$CF_PAGES_URL"

不得把这份预览产物直接发布到生产环境；生产发布前必须使用规范域名重新构建。

部署到 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，并确认在仓库根目录执行以下命令能够成功：

BASH

hugo --gc --minify

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

添加 Pages 工作流

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

 1name: Deploy Hugo site to Pages
 2
 3on:
 4  push:
 5    branches: [main]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13concurrency:
14  group: pages
15  cancel-in-progress: false
16
17env:
18  GO_VERSION: 1.26.6
19  HUGO_VERSION: 0.164.0
20
21jobs:
22  build:
23    runs-on: ubuntu-latest
24    steps:
25      - uses: actions/checkout@v7
26        with:
27          fetch-depth: 0
28          submodules: recursive
29      - uses: actions/setup-go@v6
30        with:
31          go-version: ${{ env.GO_VERSION }}
32      - name: Install Hugo Extended
33        run: |
34          curl -L -o hugo.deb \
35            "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb"
36          sudo dpkg -i hugo.deb
37      - uses: actions/configure-pages@v6
38        id: pages
39      - name: Build
40        run: >-
41          hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
42      - uses: actions/upload-pages-artifact@v5
43        with:
44          path: public
45
46  deploy:
47    environment:
48      name: github-pages
49      url: ${{ steps.deployment.outputs.page_url }}
50    runs-on: ubuntu-latest
51    needs: build
52    steps:
53      - name: Deploy
54        id: deployment
55        uses: actions/deploy-pages@v5

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

其他托管方式

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 访问能力，以便在全新构建中下载已经固定版本的模块。完整离线发行包使用相邻的 themes/oink/ 目录，可避免首次构建时下载依赖。

将配置保存在仓库中

也可以把同样的设置写入 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

OINK 站点的产物是一个纯静态目录。任何能托管静态文件的地方都能部署，不需要 Node 运行时、不需要服务端渲染、也不需要构建插件。

生产构建

BASH

hugo --gc --minify

产物写入 public/。这个目录可以脱离源码树独立部署。

--gc , flag: 构建后清理未被引用的缓存资源。
--minify , flag: 压缩 HTML、CSS、JS 与 XML 输出。
--baseURL , string: 覆盖配置里的 baseURL。部署到子路径时必须带上该路径。

baseURL 是最常见的故障源

部署到子路径时，baseURL 必须包含它：

BASH

hugo --gc --minify --baseURL https://example.com/docs/

配错的后果不是页面打不开，而是更隐蔽的半坏状态：页面能显示，但搜索索引 404、页面操作链接指向错误位置、部分资源加载失败。

排查时先确认浏览器请求的 offline-search-index.*.json 路径是否正确。

本章内容

Cloudflare Pages：Git 集成，构建在平台侧完成
GitHub Pages：用 Actions 构建并发布
其他托管：Netlify、S3/CloudFront 及通用静态托管
本地与离线构建：网络隔离环境

构建环境与索引控制

Hugo 的 -e 只选择构建期行为（指纹、压缩），不区分站点内容。