ReadTheDocs安装pyscard报错winscard.h缺失解决方法

之前做的两项配置不生效，核心是踩了ReadTheDocs（以下简称RTD）的执行顺序坑：

• autodoc_mock_imports是Sphinx启动后、扫描源码生成文档阶段才生效的模块模拟配置，但pip安装依赖的步骤在Sphinx启动之前，根本等不到mock生效就会因为pyscard编译失败中断构建
• RTD默认不会自动执行setup.py里的依赖过滤逻辑，默认流程是直接读取你指定的requirements文件全量安装，你写在setup.py里的READTHEDOCS环境判断，只有当RTD走pip install .安装项目本身的时候才会触发，如果你配置的是直接安装根目录requirements.txt，这段逻辑完全不会执行。

报错里的fatal error: winscard.h: No such file or directory是因为pyscard是带C扩展的Python包，编译时依赖PCSC智能卡库的开发头文件，RTD默认构建镜像里没有预装这个系统库，所以编译直接失败。

方案1：拆分文档专用依赖（最推荐，一劳永逸） #

• 在docs目录下新建专门给文档构建用的依赖文件docs_requirements.txt，里面只列文档构建必需的包，比如sphinx、sphinx-rtd-theme、myst-parser这类，不要加入pyscard
• 在仓库根目录新建RTD专属配置文件.readthedocs.yaml，明确指定构建流程，跳过根目录运行时requirements.txt的安装，示例配置：

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
python:
  install:
    # 先装文档专用依赖
    - requirements: docs/docs_requirements.txt
    # 再以可编辑模式安装项目本身，这一步会触发setup.py里的环境判断，自动过滤pyscard
    - method: pip
      path: .

• 之前配置的autodoc_mock_imports = ['pyscard']保留即可，Sphinx扫描源码导入时会自动模拟pyscard模块，不会报导入错误。

方案2：安装编译依赖（如果必须在文档环境装pyscard） #

如果因为特殊原因不能拆分依赖，必须在RTD构建时安装pyscard，可以直接在RTD配置里提前安装pyscard编译需要的系统依赖，示例配置：

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  # 提前装pyscard编译需要的系统包
  apt_packages:
    - libpcsclite-dev
    - swig
python:
  install:
    - requirements: requirements.txt

其中libpcsclite-dev会提供缺失的winscard.h头文件，swig是pyscard生成Python C扩展绑定代码的必需工具，两个包装完后pyscard就能正常编译安装。

避坑提醒 #

不要试图只靠autodoc_mock_imports解决安装阶段的报错，这个配置的生效阶段决定了它管不到pip装包的过程，之前配置不生效就是这个原因。

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