升级迁移

• 1: 升级 Oink Hugo Module
• 2: 升级 Oink Git submodule 或克隆
• 3: 从 Docsy npm 包迁移
• 4: 迁移现有 Docsy 站点

hugo version

hugo --gc --minify

1 - 升级 Oink Hugo Module

固定版本

生产站点应导入发布标签或不可变的 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 - 升级 Oink Git submodule 或克隆

请根据安装方式选择相应步骤：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；消费站点只保留真正属于站点的覆盖。

随后继续审查主题覆盖。

3 - 从 Docsy 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。

随后继续审查主题覆盖。

4 - 迁移现有 Docsy 站点

OINK 旨在替换各站点复制的公共外壳、运行时与短代码，而无需批量重写普通正文。安全迁移应按依赖关系删除覆盖项，把产品专用行为留在站点，并在修改生产环境前先验证临时副本。

迁移原则

• 固定目标实现，不要把生产站点迁移到未固定版本的分支。
• 删除覆盖项之前先完成清点。
• 删除公共主题副本，不删除站点业务逻辑。
• 在 OINK API 兼容的地方，保持内容 URL、front matter 与短代码行为不变。
• unsafe 或在线例外必须显式声明，并且只在过渡期使用。
• 分别测试构建产物、浏览器行为与托管站点行为。

固定目标版本

请在 go.mod 中固定已发布标签，或使用完整的版本化归档。预发布评估期间，Hugo Module 站点可以使用被忽略的 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

站点的 hugo.yaml 导入 github.com/pgsty/oink；workspace 只替换本地 checkout。

清点现有覆盖项

把每个站点级文件归入以下四类之一：

layouts/、assets/、static/、配置与构建工作流必须一起检查。复制的短代码通常还伴随一份 JavaScript bundle、样式表、vendor 文件和 CI 安装步骤。

迁移配置

搜索与品牌

启用主题提供的本地搜索，并让外壳使用站点自己的 Logo：

params:
  logo: img/product.svg
  offlineSearch: true

继续在原有语义位置使用 title、languages.*、github_repo、github_project_repo、 github_branch、page_width 与 ui.*，不要把它们迁入 oink.* 命名空间。

字体

旧 Sass 开关 $td-enable-google-fonts: true 现在会选择 OINK 随附的本地 Open Sans，而不会请求 Google Fonts。$td-web-font-path 不再参与当前构建。需要其他字体的站点必须提供获准使用的本地资源及其许可证。

删除公共覆盖项

临时构建证明等价后，可以删除站点中的以下副本：

• layouts/baseof.html 与公共 docs/blog baseof*.html；
• 公共 navbar、footer、sidebar、目录（TOC）、search、head CSS partial 及相应 hook；
• 旧的公共品牌文档外壳 partial；
• asciinema、echarts、infographic、doc-carousel、details、 tab/tabpane、card 与 param 短代码副本；
• 只服务于上述已删除实现的 JavaScript、Lunr 副本、轮播代码与 SCSS；
• 不再被任何站点资源需要的消费端 PostCSS 与 Autoprefixer 步骤。

应按引用关系删除，而不是直接清空 layouts/。首页、下载页与门户仍可能调用本地 icon、search dialog、blog row 或 tag filter 等 partial。

保留站点专用行为

保留语义属于具体产品的内容与代码：

• 产品矩阵与兼容性数据；
• 价格、下载、门户、解决方案与目录页面；
• 站点专用首页结构；
• 自定义重定向、响应头、分析或身份集成；
• 承载业务数据、而非通用呈现逻辑的内容组件。

对于 Pigsty 家族，pgvers、pgext_matrix、pgext_os_matrix、home-docs 以及当前 metric 实现继续留在站点层。

参考站点矩阵

当前迁移计划采用以下边界：

该矩阵是清点工作的起点，并不意味着可以删除所有名称相似的文件。必须在目标检出目录中解析实际模板引用。

演练工作流

请在消费站点的临时副本中演练迁移。应用本地 Oink workspace，每次删除一组计划覆盖项，阻断非预期网络与前端工具访问，再执行生产构建：

HUGO_MODULE_WORKSPACE=go.work hugo --gc --minify

演练不得修改源工作区。保留失败副本用于诊断，并记录准确的主题 commit、Hugo 版本、已删除文件与输出数量。

当前证据

最近一次记录的演练发生在 2026-08-08，使用 Hugo Extended 0.164.0：

这些是临时副本的构建结果，不代表四个生产站点已经完成迁移或部署。

生产迁移流程

对每个站点依次执行：

1. 创建专用迁移分支；
2. 固定 OINK 候选版本并记录其源码提交；
3. 每次只删除一组内聚的覆盖项；
4. 执行干净的 Hugo-only 构建与针对性自动化测试；
5. 比较具有代表性的首页、文档页、博客页、特殊页面与 404 页面；
6. 检查移动导航、两种颜色模式、语言切换、搜索、打印与站点保留的业务组件；
7. 部署预览，并验证真实 URL 与网络请求；
8. 评审通过后才合并并部署，随后执行生产冒烟测试。

对于 OINK 有意改变外壳的部分，应记录合理差异，而不是强求像素级相同。

回滚

保留迁移前的主题 pin、站点提交与已知可用部署产物。回滚时三者应一致恢复。针对新主题只重新引入一部分随机复制布局，会形成比任一完整版本都更难诊断的混合状态。