部署站点

一次构建 Oink，发布静态产物并验证结果。

OINK 部署包含两个独立阶段：Hugo 先生成完整的 public/ 目录，静态托管服务再发布该目录。请把构建验证与线上验证分开，避免把一次成功的本地命令误认为已经完成生产发布。

生产构建

在站点根目录使用固定版本的 Hugo Extended 运行：

hugo --gc --minify --cleanDestinationDir

--gc 会清理不再使用的缓存资源，--minify 生成生产资源，--cleanDestinationDir 删除上次构建残留的文件。如果 publishDir 不是站点专用输出目录，使用最后一个参数前必须先检查命令目标。

构建应顺利完成，并且不能用忽略告警的方式掩盖缺失内容、端点或资源。上传前请先在本地检查 public/。

本地预览

编辑期间运行：

hugo server --disableFastRender

Hugo 开发服务器只能证明源码可以渲染；它不是生产托管服务，实时重载行为也不属于生成后的站点。每次发布前都应执行一次干净的生产构建。

构建环境与索引

普通 hugo 命令使用 production 环境。Oink 会把生产构建的 HTML 标记为允许索引，并使用经过优化和指纹处理的资源。公开预览如不应被搜索引擎索引，请改用其他环境构建：

hugo --environment preview --baseURL "https://preview.example.com/"

Oink 会在非生产环境输出 noindex, nofollow。托管层的 X-Robots-Tag 响应头可作为纵深防护，对非 HTML 文件尤其有用。发布到 canonical URL 前，应以 production 环境重新构建已经审查的源码；预览产物不等于生产产物。

静态托管

任何能够提供目录和文件的主机都可以发布 OINK：

对象存储与 CDN；
GitHub Pages、GitLab Pages 或类似的 Git 驱动静态托管；
Netlify、Cloudflare Pages 或其他构建并发布的平台；
Nginx、Caddy、Apache 或内部文件服务器。

请把 baseURL 设置为生产环境 canonical URL。如果站点发布在 https://example.com/manual/ 之类的子路径下，应包含该路径并进行测试；OINK 的本地资源与组件 URL 设计为支持子路径部署。

Cloudflare Pages

让 Pages 直接连接源分支。OINK 不需要由 GitHub Actions 预先构建并推送孤立 Pages 分支。

Oink 站点可使用以下设置：

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

截至 2026-08-08，Cloudflare Pages v3 构建镜像文档中的默认 Hugo 版本为 0.147.7，低于 OINK 最低要求 0.160.1。应当在 Production 与 Preview 中都显式设置 HUGO_VERSION，不要依赖持续变化的平台默认值。 SKIP_DEPENDENCY_INSTALL=1 可阻止平台的通用依赖安装器增加站点并不需要的前端安装步骤。

预览环境如需使用 Pages 生成的地址作为构建 canonical URL，可以运行：

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

Cloudflare 官方文档把 public 列为 Hugo 标准输出目录，并说明了 HUGO_VERSION 覆盖与 CF_PAGES_URL base URL 用法。调整构建镜像或固定 Hugo 版本时，请重新核对平台文档。

参阅 Cloudflare Hugo 指南与Cloudflare 构建镜像。

网络隔离部署

在断网环境中，应同时传入站点源码与已经验证的主题归档，而不是依赖首次构建时下载 Hugo Module：

验证主题归档附带的 SHA-256 文件；
在环境中安装受支持的 Hugo Extended 二进制文件；
把主题解压到站点的 themes/oink/ 目录；
设置 theme: oink，并在站点中运行 hugo --gc --minify；
把 public/ 发布到内部静态服务器。

除非已经配置隔离网络内可达的端点，否则请保持 PlantUML 与 Diagrams.net 关闭。外部链接与嵌入内容仍由内容作者负责。

响应头与缓存

带指纹的 CSS 与 JavaScript 可以使用长期 immutable 缓存。HTML、搜索索引、Feed 与站点地图应使用较短缓存或重新验证，以便新部署及时生效。

支持 _headers 约定的托管平台可以读取站点自有的 static/_headers 文件。这不是可移植标准；应根据站点实际使用的行内内容与集成审查安全响应头。

预览与生产 URL

canonical、hreflang、Open Graph、Feed 与绝对链接都依赖 baseURL。生产构建应使用生产 URL；如果链接验证或社交元数据需要准确，预览构建可以使用临时地址。

不要把针对预览地址生成的产物直接发布到生产环境；反过来，也不要因为预览中出现有意传入的预览域名就判定失败。

部署验收

每一层都要独立验证：

源码与配置

预期提交与固定主题版本确实存在；
baseURL、语言、菜单、仓库元数据与可选端点正确；
未发布草稿或秘密信息没有进入公开内容树。

构建产物

使用固定版本的 Hugo Extended 完成干净生产构建；
英文、中文、Feed、站点地图、搜索索引与 404.html 均存在；
本地资源在根路径与配置的子路径下都能解析；
产物包含所需许可证与归属说明。

托管站点

生产 URL 返回新产物；
canonical 与备用语言 URL 使用生产域名；
导航、搜索、语言切换、深色模式、打印和代表性组件在真实浏览器中工作；
重定向、自定义响应头、缓存策略与 404 行为符合配置；
“支持网络隔离”的结论有浏览器网络审计作为依据。

绿色构建日志只完成产物阶段；托管检查全部通过后，部署才算完成。

回滚

保留上一份已知可用的静态产物或托管平台部署标识。新版本未通过线上验证时，应先恢复该产物，再诊断源码或平台行为。使用新的、未固定工具链重新构建旧提交，并不等同于恢复原产物。