Read the Docs使用nbsphinx构建文档：两类构建报错的排查方法

第一阶段初始报错定位 #

最初抛出ModuleNotFoundError: No module named 'nbsphinx'的核心原因非常明确：Read the Docs的远程构建环境和你本地环境完全隔离，构建机从零拉取依赖，不会自动识别你本地pip安装的任何包。因为你没有在专属配置文件里声明nbsphinx等构建依赖，Sphinx初始化加载扩展的时候自然找不到对应模块。

第二阶段conda配置报错定位 #

后续抛出Invalid "conda.environment": environment not found的错误，是参考配置教程时常见的抄配置漏写、路径错配问题，按以下检查项逐一排查即可：

• 检查配置文件的存放路径与文件名
  Read the Docs只会自动识别项目根目录下、文件名严格为.readthedocs.yaml（无多余字符、文件名开头带点）的配置文件。如果你把配置写在了docs子目录、或者文件名写错成readthedocs.yml/.readthedocs.yml，RTD根本不会读取，反而会因为平台默认的配置检测逻辑，错误触发conda环境路径不存在的报错。
• 检查配置语法的匹配性
  绝大多数场景下根本不需要启用conda构建通道：你可以直接在.readthedocs.yaml的python.install段声明pip依赖路径，完全不需要写顶层conda:配置段。很多人跟着教程抄配置时，不加判断把conda段直接写进来，但自己根本没有准备对应的conda环境文件，直接就会触发这个报错。
• 检查路径引用的正确性
  如果确实需要使用conda构建通道，配置里写的环境文件路径必须是相对于项目根目录的相对路径，不能写本地绝对路径、不能漏写子目录层级。比如你的conda环境文件放在docs目录下，正确写法是conda.environment: docs/environment.yml，如果实际文件在这个路径之外，RTD就会抛出环境找不到的错误。
• 检查平台后台的设置冲突
  打开Read the Docs项目的「高级设置」页，检查是否手动勾选了“使用conda环境构建”的开关：如果开关被打开，但配置文件里的路径写的不对，就算本地文件结构正确，RTD也会因为校验不通过报错。

可直接落地的正确配置方案 #

针对你用nbsphinx渲染Jupyter Notebook文档的场景，直接替换成无多余conda配置的轻量方案即可完全避开上述问题：

1. 在项目根目录放置严格命名为.readthedocs.yaml的配置文件，内容参考：

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
python:
  install:
    - requirements: docs/requirements.txt  # 路径对应你实际存依赖文件的位置
sphinx:
  configuration: docs/source/conf.py  # 路径对应你实际存Sphinx配置的位置

2. 在对应路径创建docs/requirements.txt，写入所有和本地环境对齐的构建依赖：

sphinx>=5.0
nbsphinx>=0.9
ipykernel

3. 确认RTD项目「高级设置」里关闭conda构建的开关，重新触发构建即可。

构建校验小技巧 #

修改完配置后，看RTD构建日志的最开头几行，只要出现Using config file at <项目路径>/.readthedocs.yaml的打印，就说明RTD成功读取了你的配置，后续的依赖安装阶段会自动把nbsphinx等包装进构建环境，不会再报找不到模块的错误。

内容的提问来源于stack exchange，提问作者J Agustin Barrachina