部署

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

生产构建

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

hugo --gc --minify --cleanDestinationDir

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

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

本地预览

编辑期间运行：

hugo server --disableFastRender

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

静态托管

任何能够提供目录和文件的主机都可以发布 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 分支。

当前 starter 使用以下设置：

截至 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：

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

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

响应头与缓存

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

项目站点提供了适用于部分托管平台的 static/_headers 示例。它只是起点，并非可移植标准。应根据站点实际使用的行内内容与集成审查安全响应头。

预览与生产 URL

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

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

部署验收

每一层都要独立验证：

源码与配置

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

构建产物

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

托管站点

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

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

回滚

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