Sphinx在PyCharm项目中误判未修改文件已变更的问题求助

针对你遇到的Sphinx每次构建都误判未修改文件为变更的问题，结合你描述的现象，整理几个实际可操作的排查方向和解决办法：

1. 清空Sphinx的依赖缓存 #

Sphinx靠.doctree目录里的缓存文件跟踪文档依赖，一旦缓存损坏就会乱判变更。别只删输出文件夹，要彻底清缓存：

• 找到项目下的_build/.doctree目录，直接删掉整个文件夹；
• 终端执行构建时加-E参数强制全量重建：sphinx-build -b html . _build/html -E；
• 如果用PyCharm内置构建，在构建配置里勾选「Clean before build」。

2. 修正文件时间戳异常 #

系统时间调整、PyCharm自动保存、同步工具都可能篡改文件时间戳，Sphinx靠这个判断是否要重建：

• Linux/macOS终端执行touch 受影响的文件.rst，手动更新时间戳；
• Windows用copy /b 受影响的文件.rst +,,（两个逗号）更新；
• 先确认本地系统时间和时区是否正确，避免新旧文件时间戳逻辑混乱。

3. 检查toctree的引用格式差异 #

你提到Doc4引用Doc3没问题但Doc5会误判，大概率是两者toctree写法有细微差别：

• 对比Doc4和Doc5的toctree代码，看是否有路径格式（绝对/相对）、:glob:参数、空格/特殊字符、大小写匹配的差异；
• 把Doc5的toctree改成和Doc4完全一致的写法，测试是否还会误判；
• 确保所有引用的文件名、路径和实际文件完全匹配（比如大小写敏感系统里别写错文件名大小写）。

4. 排查Sphinx版本或扩展问题 #

如果近期更过Sphinx版本或加了新扩展，可能是兼容性问题：

• 回退到之前正常工作的Sphinx版本：pip install sphinx==x.x.x（替换成你之前用的版本号）；
• 暂时禁用所有第三方扩展，逐个重新启用排查哪个扩展搞的鬼。

5. 清空PyCharm的IDE缓存 #

PyCharm的缓存可能和实际文件系统不同步：

• 执行File -> Invalidate Caches... -> Invalidate and Restart，清空缓存后重启IDE再构建。

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