Sphinx重复目标静默覆盖、超链接ref引用失效问题咨询

• 该现象是Sphinx旧版本核心逻辑的默认行为，不属于配置错误。
• Docutils原生仅会检测单个rst文件内的重复显式目标并抛出告警，跨文档的全局引用目标收集是Sphinx独立实现的逻辑。在Sphinx 6.0版本之前，核心代码未加入跨文档重复标签的检测规则：构建时全局标签表按文档处理顺序写入，处理顺序由toctree声明顺序、文档间引用依赖关系决定，遇到已存在的同名标签会直接跳过，不输出任何提示，最终仅保留最先被处理到的目标，后续同名目标被静默覆盖。
• 测试中观察到的目标生效位置随文件迁移变化，本质是文档处理顺序发生改变，最先被扫描到的.. _abc:被写入全局标签表，其余位置的同名目标被直接忽略。
• 若需要开启重复目标告警，可选择两种方案：
  • 升级Sphinx至6.0及以上版本，核心默认会对跨文档重复标签抛出明确告警；
  • 若需使用旧版本，可通过第三方扩展实现重复目标检测，旧版本自带的nitpicky模式默认不覆盖该类检测场景。

• 该现象由Sphinx的角色设计边界决定，两类显式目标的注册逻辑完全不同：
  • 无后缀的内部位置目标（即.. _abc:后无内容，锚定当前文档位置）会被注册到Sphinx标准域的全局label表中，属于内部文档定位标识，仅这类目标可被:ref:角色查找、引用。
  • 带URL的外部链接目标（即.. _abc: 外部链接地址格式）是Docutils原生的单文档级链接替换规则，不会被Sphinx收集到全局label表，默认作用域仅限定义它的单个文件，本身不在:ref:的查找范围内，因此会触发未定义标签告警。
• 跨文档复用外部URL不需要配置复杂的base规则，最轻量的实现方式是在conf.py中配置rst_epilog，将公共外部链接统一定义在该配置项中，所有文档构建时会自动加载这些定义，在任意页面直接使用reST原生的链接标识_语法即可引用，无需调用:ref:角色。
• 配置示例：

# conf.py 内添加如下配置
rst_epilog = """
.. _abc: 你需要复用的外部URL地址
.. _other-link: 其他需要全局复用的链接
"""

配置完成后，任意rst文件内直接写访问 abc_ 查看对应内容即可正常生成跳转链接，无需在每个页面单独定义目标。

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