升级Docusaurus v3遇锚点错误：看似正确的锚点被判定失效

升级Docusaurus v3后出现失效锚点错误，所有指向术语表../glossary/#carbon-budget的链接都报错，但从代码和页面显示看锚点似乎正常，可以从以下几个方向排查：

1. 核对实际渲染的锚点ID #

Docusaurus v3对标题转锚点的规则有微调，可能和v2的生成逻辑不一致。直接查看术语表页面的实际锚点：

• 打开glossary页面，右键点击「Carbon Budget」标题，选择「检查」
• 查看对应标题标签（比如<h2>）的id属性值，确保链接中的#carbon-budget和这个id完全匹配（注意大小写、连字符等细节）

2. 修正链接路径 #

相对路径可能因页面层级变化导致错误，试试改用绝对路径：
把原链接：

[carbon budget](../glossary/#carbon-budget)

改成：

[carbon budget](/glossary/#carbon-budget)

绝对路径不受当前页面位置影响，能避免层级匹配错误。

3. 清理构建缓存 #

升级后残留的旧缓存可能导致锚点映射异常，执行以下命令清理后重新构建：

npm run clear
npm run build

4. 排查插件/主题冲突 #

如果用了第三方插件或自定义主题，可能和Docusaurus v3的锚点生成逻辑冲突：

• 临时禁用所有非官方插件，重新构建看是否还报错
• 逐步恢复插件，找到冲突的那个后更新到兼容v3的版本，或替换为官方插件

5. 检查标题中的隐藏字符 #

术语表的「Carbon Budget」标题可能包含看不见的特殊字符（比如全角空格、零宽空格），导致生成的锚点和你写的carbon-budget不一致：

• 手动重新输入标题内容，不要复制粘贴
• 确保标题只有正常的字母和空格，然后重新构建

你用到的锚点代码：

:::tip 72-144.3 Gigatons will be saved from our [carbon budget](../glossary/#carbon-budget)
:::

术语表对应位置截图：

内容的提问来源于stack exchange，提问作者museum