# 从 Docsy 0.11.0 升级到 0.12.0

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

---

我们没有为 0.12.0 发布版本公告，因此借此机会完整介绍从 [0.11.0][] 升级到
[0.12.0][] 的过程。

> **摘要**：Docsy [0.12.0][]
> 的主要破坏性变更来自 Hugo 的[新模板系统][NTS]，它改变了 `layouts`
> 子目录和文件名。

本文将依次完成以下升级：

- **[Docsy](#update-docsy)**：[0.11.0][] → [0.12.0][]
- **[Hugo](#update-hugo)**：0.136.2 → 0.147.5[^vers-note]
- **[Node](#update-nodejs)**：LTS 20 → LTS 22[^vers-note]

[0.11.0]: /zh/project/about/changelog/#v0.11.0
[0.12.0]: /zh/project/about/changelog/#v0.12.0

[^vers-note]:
    以上是对应 Docsy 版本正式支持的 Node.js 与 Hugo 版本。更高版本可能可以工作，但不在正式支持范围内。

> [!NOTE]
>
> 本文覆盖最常见的升级步骤。项目定制项可能还需要额外调整。建议在 **独立分支**
> 中完成这些变更，并在部署到生产环境前进行 **全面测试**。

## 流程概览 {#procedure-overview}

1. [更新 Docsy 与 Hugo 版本](#update-docsy-hugo-and-more)
2. [移动自定义布局文件与目录](#move-custom-layout-files-and-folders)
3. [检查其他必要变更](#check-for-additional-required-changes)
4. [测试站点](#test-your-site)

## 更新 Docsy、Hugo 及其他依赖 {#update-docsy-hugo-and-more}

### 1. 更新 Node.js {#update-nodejs}

Docsy 正式支持当前活跃的 Node.js LTS 版本。在 0.12.0 发布时，该版本是 Node.js
22。建议使用 [nvm][] 更新：

```sh
nvm install --lts
```

该命令会安装最新 LTS，并在当前 Shell 会话中选中它（适用于 Linux 与 macOS）。

[nvm]: https://github.com/nvm-sh/nvm

### 2. 更新 Docsy {#update-docsy}

> [!IMPORTANT]
>
> 升级到 [0.16.0](/zh/blog/2026/0.16.0/)
> 或更高版本时，请使用[更新 Docsy](/zh/docs/update/)流程。

- 使用 NPM：

  ```bash
  npm install --save-dev google/docsy#semver:0.12.0
  ```

- 使用 Hugo Module：

  ```bash
  hugo mod get -u github.com/google/docsy@v0.12.0
  ```

- 使用 Git Submodule：

  ```bash
  cd themes/docsy
  git fetch --tags
  git checkout v0.12.0
  cd ../..
  git add themes/docsy
  ```

### 3. 更新 Hugo {#update-hugo}

先把 Hugo 更新到 0.147.5，即使最终目标是更高版本也应如此。建议在完成 Docsy 升级后，再通过独立步骤升级到更高版本。

具体方法取决于项目如何管理 Hugo 依赖。使用 [hugo-extended][]
的项目应更新 NPM 软件包版本，同时更新 NPM
Lockfile 或缓存键，强制刷新 CI/CD 缓存。例如：

```bash
npm install --save-exact -D hugo-extended@0.147.5
```

[hugo-extended]: https://www.npmjs.com/package/hugo-extended

### 4. 安装依赖 {#install-dependencies}

使用 Git Submodule 时，安装 Docsy 依赖：

```bash
npm install
(cd themes/docsy && npm install)
```

## 移动自定义布局文件与目录 {#move-custom-layout-files-and-folders}

为了与 Hugo 的[新模板系统][NTS]保持一致，Docsy v0.12.0 重新组织了 `layouts`
目录[^2]。这不是强制要求，但建议按以下方式更新项目布局文件与目录，使其符合 Hugo 新结构：

[^2]: 实现细节见 Issue [#2243][]。

- 将 `_markup` 上移一级：

  ```text
  layouts/_default/_markup/  → layouts/_markup/
  ```

- 为子目录添加下划线前缀：

  ```text
  layouts/partials/     → layouts/_partials/
  layouts/shortcodes/   → layouts/_shortcodes/
  ```

- 移动并重命名[分类文件](#taxonomy-files)（如适用）：

  ```text
  layouts/_default/taxonomy.html → layouts/term.html
  layouts/_default/terms.html    → layouts/taxonomy.html
  ```

以下命令可以帮助移动自定义布局文件与目录 <a id="move-layout-files"></a>：

1. 移动自定义布局文件与目录：

   ```bash
   # If you have custom partials
   git mv layouts/partials/* layouts/_partials/

   # If you have custom shortcodes
   git mv layouts/shortcodes/* layouts/_shortcodes/

   # If you have custom markup render hooks
   git mv layouts/_default/_markup/* layouts/_markup/

   # If you have custom taxonomy layouts
   git mv layouts/_default/taxonomy.html layouts/term.html
   git mv layouts/_default/terms.html layouts/taxonomy.html

   # Clean up empty directories
   rmdir layouts/partials layouts/shortcodes layouts/_default/_markup layouts/_default
   ```

2. 更新 Docsy 模板引用。

   如果 `layouts/_markup/render-heading.html` 引用了 Docsy 标题模板：

   ```diff
   - {{ template "_default/_markup/td-render-heading.html" . -}}
   + {{ partial "td/render-heading.html" . -}}
   ```

   请注意，`td` 前缀从文件名移到了目录路径。

## 检查其他必要变更 {#check-for-additional-required-changes}

### 1. 图片指纹 {#image-fingerprints}

如果项目 CSS/SCSS **没有** 使用 `blocks/cover`
[首屏/背景图片][images]，请跳过本步骤。

Hugo 会生成新的图片[指纹][]。在 CSS/SCSS 中引用[首屏/背景图片路径][images]的项目，需要更新为新指纹；严格配置内容安全策略（CSP）的项目也包括在内。

1. 构建站点：`npm run build`；
2. 在 `public` 或 `resources/_gen/images/` 中检查带新指纹的图片文件名；
3. 更新样式表中的引用。

[指纹]: https://gohugo.io/functions/resources/fingerprint/
[images]: /zh/docs/content/iconsimages/#landing-pages

### 2. 分类文件 {#taxonomy-files}

如果项目覆盖分类布局，除了移动文件，还要：

- **交换** 布局文件；
- 将 `terms` 文件名改为 **单数**：`terms.html` → `term.html`。

CLI 命令见[移动布局文件](#move-layout-files)步骤。

### 3. 内部布局 `content.html` 文件重命名 {#content-html-rename}

如果项目覆盖 Docsy `layouts/**/content.html` 文件：

- 为文件名添加 `_td-` 前缀：`content.html` → `_td-content.html`。

受影响文件如下：

```text
layouts/_td-content-after-header.html
layouts/_td-content.html
layouts/blog/_td-content.html
```

## 测试站点 {#test-your-site}

构建站点并检查错误，尤其是找不到模板和布局文件缺失：

```bash
npm run build
```

建议同时执行开发构建与生产构建。

随后启动站点，确认渲染结果符合预期。例如：

```bash
npm run serve
```

### 测试清单 {#testing-checklist}

使用以下清单确认升级成功：

- [ ] 构建成功，且没有错误、警告或弃用通知；CSS 与其他资源均已渲染；
- [ ] 首页、文档页、博客文章等关键页面可以加载，没有 404 或布局损坏；
- [ ] 导航链接可解析，面包屑显示当前路径，当前分区正确高亮；
- [ ] 移动端或平板上导航可用，关键页面没有横向滚动；
- [ ] 外部链接显示预期样式，例如图标；
- [ ] [标题自链接][]工作正常且样式正确；
- [ ] 深色模式切换正常（如启用）；
- [ ] 自定义短代码正确渲染（如使用）；
- [ ] 搜索返回预期结果（如使用）；
- [ ] 打印预览正确（如使用）。

[标题自链接]: /zh/docs/content/navigation/#heading-self-links

## 参考资料 {#references}

完整发布说明见：

- [Docsy v0.12.0 Changelog](/zh/project/about/changelog/#v0.12.0)
- 从 0.136.2（或项目起始版本）到 0.147.5 的
  [Hugo 发布说明](https://github.com/gohugoio/hugo/releases)

其他参考资料：

- [Hugo 0.146.0 模板系统][NTS]
- [0.11.0 版本亮点](../2024/year-in-review/#release-highlights)
- [0.11.0 Changelog](/zh/project/about/changelog/#v0.11.0)
- [Docsy Issue #2243][#2243]：_适配 Hugo v0.146.0 新模板系统_
- [0.13.0 发布报告与升级指南](/zh/blog/2025/0.13.0/)——从 0.12.0 升级到 0.13.0

[#2243]: https://github.com/google/docsy/issues/2243
[NTS]: https://gohugo.io/templates/new-templatesystem-overview/