在Read the Docs安装依赖时遇ImportError: No module named 'Cython'

阿华AIGC实验室

2026-5-27

解决Read the Docs构建时Cython缺失的问题

我来帮你搞定这个构建错误！从日志来看，问题出在安装clustertree时，它的setup.py需要调用Cython，但Read the Docs的默认构建环境里没有预先安装Cython，导致了ImportError。下面是几个可行的解决办法：

在依赖文件中提前声明Cython
创建或修改你的项目依赖文件（比如根目录的requirements.txt，或者docs目录下的requirements-docs.txt），把Cython添加进去。这样Read the Docs在安装clustertree之前，会先安装好Cython。示例依赖内容：
```
Cython
clustertree
sphinx-autorun
# 其他你的文档依赖...
```
之后要在Read the Docs的项目设置里，指定这个依赖文件的路径（比如如果是docs/requirements-docs.txt，就把路径填进去）。
配置setup_requires（如果clustertree是你的项目）
如果你是clustertree的维护者，可以修改它的setup.py，把Cython加入setup_requires参数，这样setuptools在处理安装时会先安装Cython：
```
from setuptools import setup
from Cython.Build import cythonize

setup(
    name="clustertree",
    # 其他配置项...
    setup_requires=['Cython'],
    ext_modules=cythonize("your_module.pyx"),
    # 其他配置项...
)
```
不过这种方式对于Read the Docs的pip安装流程来说，不如直接在requirements里声明可靠，因为pip有时不会优先处理setup_requires。
确认Read the Docs构建环境的Python版本
确保Read the Docs使用的Python版本和你本地开发时的版本一致，避免因版本不兼容导致的依赖安装问题。你可以在项目的.readthedocs.yaml配置文件里指定Python版本，示例：
```
version: 2
python:
  version: 3.9
  install:
    - requirements: docs/requirements-docs.txt
```