在ReadTheDocs发布文档时遇pywin32==305匹配失败的解决办法

核心原因 #

pywin32是Windows专属的Python库，ReadTheDocs的构建环境基于Linux，且pywin32==305没有适配Linux的分发包；另外就算你移除了requirements.txt里的pywin32声明，也可能有其他依赖包间接拉取了这个特定版本。

具体解决步骤 #

• 排查间接依赖：安装pipdeptree工具（执行pip install pipdeptree），生成项目依赖树，定位哪个包强制依赖了pywin32==305。找到后可尝试升级该包到兼容版本，或给该包添加条件依赖限制。
• 添加平台条件依赖：如果确实需要pywin32，在requirements.txt里指定仅Windows环境安装：

  pywin32==305; sys_platform == 'win32'
  

  这样Linux环境的ReadTheDocs会自动跳过这个依赖的安装。
• Mock Windows专属模块：文档构建不需要实际运行pywin32功能，在Sphinx配置文件docs/conf.py里添加mock代码，让Sphinx忽略相关模块：

  import sys
  from unittest.mock import Mock
  
  # 按需mock pywin32的子模块
  win32_modules = ['win32api', 'win32con', 'win32gui', 'pywin32']
  for mod in win32_modules:
      sys.modules[mod] = Mock()
  

• 清理ReadTheDocs缓存：进入项目的ReadTheDocs构建页面，触发「重新构建」并勾选「清除所有缓存」，确保构建环境拉取最新的依赖配置，而非使用旧缓存。
• 检查自定义构建脚本：如果项目有readthedocs.yml或自定义构建脚本，检查里面是否硬编码了安装pywin32==305的命令，如有则修改或移除。

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