# 弃用说明
> Hugo 弃用功能、方法与配置项的流程，以及升级时如何查看提示。
- 官方英文原文：https://gohugo.io/troubleshooting/deprecation/
- 本页规范地址：https://hugozh.cn/troubleshooting/deprecation/
- 最近更新：2026-10-02
- 最后提交：912b1d3 chore(site): 添加 static/CNAME（hugozh.cn），供 GitHub Pages 等平台绑定自定义域名
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译，如有出入以官方英文原文为准

---
## 什么是弃用

当一个项目宣布某项内容「弃用」（deprecate）时，它是在告诉用户三件事：

1. 不要再使用「甲」了。
2. 请改用「乙」。
3. 我们会在将来某个时间点移除「甲」。

常见的[弃用原因](https://en.wikipedia.org/wiki/Deprecation)包括：

- 某项功能已被更强大的替代方案取代。
- 某项功能存在设计缺陷。
- 某项功能被认为是多余的，为了简化整个系统，将来会被移除。
- 软件的后续版本会有重大结构调整，导致继续支持旧功能不可能或不切实际。
- 为了统一命名或提高一致性。
- 过去只能独立使用的功能，现在与其配套功能合并。

## 弃用的节奏

项目团队在代码中弃用某项内容之后，Hugo 会：

1. 在 3 个次版本（minor release）中记录 INFO 级别的消息；
2. 再在 12 个次版本中记录 WARN 级别的消息；
3. 此后记录 ERROR 级别的消息，并让构建失败。

这里的次版本指版本号中第二段数字递增的发布，例如 v0.1.1 => v0.2.0 就是一个次版本。

## 文档的处理

项目团队会：

1. 在弃用日期当天更新文档，加入说明弃用的注记以及相关的替代方案；
2. 在 Hugo 开始记录 ERROR 消息并导致构建失败之后的 6 个或更多次版本后移除代码。到那时 Hugo 仍然会抛出错误，但错误消息中不再提到弃用；
3. 在弃用日期两年之后移除对应的文档。

因此，升级 Hugo 时看到弃用提示，最好当场处理，而不要等到功能被移除。

## 如何查看弃用提示

要看 INFO 级别的消息，必须使用 `--logLevel` 命令行标志：

```bash
hugo build --logLevel info
```

只想保留弃用相关的提示时，可以过滤输出：

```bash
hugo build --logLevel info | grep deprecate
```

如果不指定 `--logLevel`，默认只会显示警告与错误，弃用初期的 INFO 提示就被淹没了，因此请在每次升级 Hugo 之后运行上面的命令。日志级别的完整说明见[日志](/troubleshooting/logging/)，`hugo build` 的其他选项见[命令](/commands/)。