# 更新 OINK

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

---

LLMS index: [llms.txt](/oink.pgsty.com/llms.txt)

---

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

<a id="update-node"></a>

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

## 更新前的准备 {#before-you-update}

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

## 更新顺序 {#update-order}

请按以下顺序更新：

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

## 更新 Hugo {#update-hugo}

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

```sh
hugo version
```

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

## 更新主题 {#update-theme}

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

- [Hugo 模块](hugo-module/)
- [Git submodule 或克隆](git/)
- [从上游 npm 包迁移](npm-package/)

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

## 审查主题覆盖 {#update-overrides}

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

- `assets/`
- `i18n/`
- `layouts/`
- `static/`

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

## 检查站点 {#check}

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

```sh
hugo --gc --minify
```

至少验证以下项目：

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

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

---

Section pages:

- [更新 OINK Hugo 模块](/oink.pgsty.com/zh/docs/update/hugo-module/): 更新以固定版本 Hugo 模块形式导入主题的站点。
- [从 Docsy npm 包迁移](/oink.pgsty.com/zh/docs/update/npm-package/): 从 OINK 消费站点中移除上游 npm 主题包。
- [更新 OINK Git submodule 或克隆](/oink.pgsty.com/zh/docs/update/git/): 更新以 Git submodule 或克隆形式保存的 OINK 主题。
- [将 Docsy 站点迁移到 OINK](/oink.pgsty.com/zh/docs/update/convert-site-to-module/): 用仅依赖 Hugo 的 OINK 主题替换 Docsy 消费端工具链。