MyST隐式引用本地正常但Read The Docs失效求助

问题背景 #

使用Sphinx构建文档，通过MyST解析Markdown文件，采用隐式文本方式创建跨引用（如[](#my-heading)或[](#MyPyClass)）。本地环境中该方式可正常工作，但在Read The Docs（RTD）上出现链接文本未填充、跨页面引用解析失败的问题。已确认本地与RTD环境使用相同版本的Python（3.10）、Sphinx（v7.3.7）和myst_parser（3.0.1）。

本地与RTD表现差异 #

本地正常表现 #

• 同页面引用：See [](#my-heading)会生成带超链接的「See My Heading」内容，可正常跳转至对应章节。
• 跨页面引用：在file1.html中使用[](#MyPyClass)，会生成指向file://path/modules/classes#MyPyClass的链接，链接文本为"MyPyClass"；若使用完整点分片段[](#modules.classes.MyPyClass)，链接文本则为"modules.classes.MyPyClass"。

RTD上的问题 #

• 问题1：同页面引用失效：在包含# My Heading的页面使用see [](#my-heading)，仅生成空链接块see <a href=#my-heading></a>，未填充预期的「My Heading」文本。
• 问题2：跨页面引用失效：使用[](#MyPyClass)或[](#modules.classes.MyPyClass)时，链接文本为空，且仅生成文件内引用（如file1.html#MyPyClass），无法跳转至目标页面。

可能原因 #

• RTD构建缓存干扰：RTD默认启用构建缓存，若缓存未正确更新，可能导致跨引用索引未重新生成，隐式文本无法被解析。
• 文档遍历/构建顺序差异：本地为全量构建，RTD可能采用增量构建或不同的文档遍历顺序，导致MyST的跨引用节点未被正确识别与关联。
• 隐藏的构建错误：RTD构建日志未显示本地出现的「未存在的myst跨引用」警告，可能是因为RTD构建时某些文档节点（如Python类的autodoc节点）未正确生成，导致跨引用无目标可匹配。
• 环境变量/构建参数差异：尽管核心依赖版本一致，但RTD的系统环境变量或Sphinx构建参数可能与本地不同，导致MyST的隐式跨引用功能未完全启用。

解决方法 #

• 强制RTD全量构建：在RTD项目的「Builds」页面点击「Rebuild with clean」，或在项目设置中关闭构建缓存，确保所有文档节点重新生成。
• 临时改用显式跨引用：暂时使用显式写法指定链接文本，如[My Heading](#my-heading)或[MyPyClass](#modules.classes.MyPyClass)，避免依赖隐式文本填充。
• 检查Sphinx配置：确认conf.py中MyST相关配置正确，例如：
  • 启用必要的扩展：extensions = ["myst_parser", "sphinx.ext.autodoc"]
  • 配置标题锚点：myst_heading_anchors = 6
  • 启用隐式跨引用支持：myst_enable_extensions = ["reference"]
• 启用RTD详细日志：在RTD项目设置中开启详细构建日志，查看是否存在autodoc模块导入失败、文档节点未生成等隐藏错误，针对性修复。

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