这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

更新 OINK

安全更新主题、Hugo Extended 与本地覆盖。

本节介绍 OINK 的更新合同。目标版本 指站点准备升级到的版本。开始之前，请先阅读对应的发布文章，其中会记录破坏性变更、必要操作和已经验证的 Hugo 版本范围。

OINK 消费端构建不安装 Node.js 软件包。npm 仍可供主题维护者使用，但不是站点更新步骤。

更新前的准备

  • 在 Git 分支或其他可恢复的站点副本上操作。
  • 记录当前固定的主题修订版本与 Hugo Extended 版本。
  • 先完整构建一次当前生产站点，以便区分新增故障与原有问题。
  • 阅读当前版本到目标版本之间的每一篇发布文章，不要跳过中间版本的迁移操作。

更新顺序

请按以下顺序更新：

  1. 如果目标版本改变了支持范围，先更新 Hugo。
  2. 根据站点的安装方式更新主题。
  3. 审查主题覆盖。
  4. 分别通过开发构建与生产构建检查站点。

更新 Hugo

安装目标版本支持的 Hugo Extended，并同步更新本地开发环境、CI、Cloudflare Pages、Netlify、容器镜像和相关缓存键。构建前先核对实际选中的二进制文件：

hugo version

当前验证基线是 Hugo Extended 0.164.0，主题当前声明的最低版本是 0.160.1。如果发布文章调整了其中任一数值，应以发布文章为准。

更新主题

根据站点的安装方式选择对应页面：

如果使用发布归档，请先保留站点自己的覆盖，再用目标版本归档替换现有主题目录。务必校验归档的 checksum，并让 LICENSE、NOTICE 与 VENDOR.json 始终随发行物保留。

审查主题覆盖

如果站点覆盖了主题文件，请逐一与新版本主题中的对应文件比较，并移植仍然适用的变更。重点检查以下目录：

  • assets/
  • i18n/
  • layouts/
  • static/

当主题已经提供相同行为时，应删除对应覆盖。带业务语义的站点组件、产品页面和品牌素材则应继续留在站点层。

检查站点

既要运行开发预览，也要执行与生产环境完全相同的命令。Hugo-only 合同下的生产构建命令是：

hugo --gc --minify

至少验证以下项目：

  • 构建完成，且没有错误、警告或弃用提示。
  • 中英文首页、文档页与博客页均能正常渲染。
  • 导航、面包屑、目录、稳定标题链接和语言切换均指向正确位置。
  • 本地搜索能返回中英文结果。
  • 深浅色模式、移动端导航与打印输出仍然可用。
  • 页面只加载实际使用的本地运行时；默认页面不发起由主题产生的第三方子资源请求。
  • Mermaid、KaTeX、Markmap、Swagger UI、Redoc 以及实际使用的内容组件仍能渲染。
  • 站点自有短代码和业务页面保持完整。

最后，执行目标版本发布文章列出的所有版本专属检查。

1 - 更新 OINK Hugo 模块

更新以固定版本 Hugo 模块形式导入主题的站点。

固定版本

生产站点应导入发布标签或不可变的 commit，绝不能跟随未固定版本的分支。在站点根目录，把 Oink 更新到指定 ref：

hugo mod get github.com/pgsty/oink@THEME_REF
hugo mod tidy

将 THEME_REF 替换为该版本发布说明指定的根标签或 commit。

测试本地 checkout

如果要在不修改已提交模块版本的前提下测试本地 OINK checkout，请使用被忽略的 Go workspace：

go work init .
go work edit -replace=github.com/pgsty/oink=/absolute/path/to/oink
export HUGO_MODULE_WORKSPACE=go.work
hugo --gc --minify

不要把包含开发者机器专属绝对路径的 go.work 提交到仓库。

验证解析出的模块

检查 Hugo 的依赖图：

hugo mod graph

确认主题解析到预期的标签、commit 或本地 replacement。OINK 不需要运行 hugo mod npm pack 或 npm install，因为浏览器依赖已经随主题提供。

随后继续审查主题覆盖。

2 - 从 Docsy npm 包迁移

从 OINK 消费站点中移除上游 npm 主题包。

上游 @docsy/theme npm 包不是 OINK 的发行渠道。OINK 将 Bootstrap、Font Awesome、字体和浏览器运行时直接随主题提供，因此消费站点只需 Hugo Extended 即可构建。

移除 npm 主题集成

首先选择一种 OINK 发行方式：固定版本的归档、Git submodule 或克隆，或者兼容 Hugo 模块。让 Hugo 能够访问该主题，并确认执行 hugo --gc --minify 时可以正确解析。

随后，从站点的 package.json 中移除 @docsy/theme，以及仅用于构建 Docsy 资源的依赖。删除 Hugo 配置中 Bootstrap 和 Font Awesome 的 npm 挂载项，同时删除只为旧主题管线存在的 PostCSS 与 Autoprefixer 构建步骤。

不要仅仅因为某项应用依赖使用 npm 就将其删除。Hugo-only 合同针对文档主题；站点自有应用或业务组件仍可能采用另一套明确且必要的工具链。

验证迁移

从全新 checkout 开始，只安装 Hugo Extended，不创建 node_modules 目录，然后执行：

hugo --gc --minify

如果站点同时支持 LTR 和 RTL 页面，请分别检查。还要验证本地字体与图标、搜索、图表、API 文档和所有已经迁移的内容组件。构建完全正常后，只有在站点自有工具也不再使用 lockfile 时，才可以删除过时的 lockfile。

随后继续审查主题覆盖。

3 - 更新 OINK Git submodule 或克隆

更新以 Git submodule 或克隆形式保存的 OINK 主题。

请根据安装方式选择相应步骤：submodule 或克隆。两种方式都必须固定到目标版本标签或不可变的 commit。

更新 submodule

在站点根目录进入主题仓库获取标签，并 checkout 目标 ref：

git -C themes/oink fetch --tags
git -C themes/oink checkout THEME_REF
git add themes/oink
git commit -m "Update OINK theme to THEME_REF"

如果站点使用其他目录名，请相应替换 themes/oink。父仓库会记录最终的 submodule commit。请推送这次父仓库提交，确保 CI 和其他贡献者解析到完全相同的源码。

无需安装任何 npm 软件包。如果某个发行版的完整主题包含仅供源码使用的嵌套 submodule，请按照该版本的说明初始化；OINK 发行物所需的浏览器运行时资源已经包含在内。

更新克隆

如果主题目录是由站点跟踪或恢复的克隆，请将其更新到目标 ref：

git -C themes/oink fetch --tags
git -C themes/oink checkout THEME_REF

沿用站点现有的可复现方式，提交、归档或记录更新后的主题。不要让生产构建持续跟随 main。

如果克隆中包含本地修改，请在切换 ref 前把它们提交到分支。更新后再通过 rebase 或其他方式重新应用，并显式解决冲突。可复用的修改应尽量回馈 OINK；消费站点只保留真正属于站点的覆盖。

随后继续审查主题覆盖。

4 - 将 Docsy 站点迁移到 OINK

用仅依赖 Hugo 的 OINK 主题替换 Docsy 消费端工具链。

这次迁移会删除复制到站点中的公共外壳覆盖，以及消费端 npm 资源管线，但不要求批量重写 Markdown 正文。

开始之前

新建工作分支，并确认现有站点能够构建。盘点 layouts/、assets/、static/ 和 i18n/ 下的自定义文件，将其分为三类：

  • 已经由 OINK 提供的 Docsy 公共外壳代码；
  • 已经由 OINK 提供的可复用组件；
  • 必须保留的站点品牌、产品页面或业务组件。

不要删除第三类文件。

选择主题发行方式

选择固定版本的 Git checkout、版本归档、完整离线发行包或公开的 Oink Hugo Module。如果要在本地临时演练，请导入 Oink，并使用 Go workspace 解析本地 checkout：

go work init .
go work edit -replace=github.com/pgsty/oink=/absolute/path/to/oink
export HUGO_MODULE_WORKSPACE=go.work
hugo --gc --minify

这样可以测试 OINK，而不会把开发者专属路径写入站点配置或 go.mod。

移除消费端资源管线

删除只用于获取 Bootstrap、Font Awesome、字体或主题浏览器运行时的 npm 挂载项与构建步骤。删除仅为 Docsy 存在的 postCSS 调用和 Autoprefixer 步骤。如果站点自有软件仍然需要 package.json，请继续保留；但文档构建本身必须能够在不安装这些软件包的情况下完成。

移除公共覆盖

OINK 直接提供文档与博客外壳、顶部导航栏、页脚、侧栏、目录、搜索、语言选择器、head 资源和核心内容组件。请按依赖关系逐组删除站点中的对应覆盖。

自定义首页、门户、下载页、产品数据和业务短代码应继续保留，直到有明确的替代实现。详细的删除/保留矩阵请参阅迁移指南。

验证结果

从全新 checkout 开始，在系统中仅提供 Hugo Extended，然后运行：

hugo --gc --minify

检查双语页面集、本地搜索、深色模式、移动端导航、打印输出、图表、API 文档、内容组件和站点专属页面。查看浏览器网络日志，确认主题默认资源均来自同源地址。

只有迁移后的构建与视觉检查全部通过，才可以删除已经过时的配置、lockfile 或工作流步骤。