Read the Docs 构建故障排查与性能优化实战指南

• 后端
• 文档

本篇技术指南以 readthedocs.org 官方文档中的"故障排查"（Troubleshooting）专题为核心，系统梳理了使用 Read the Docs 构建文档时最常见的两类问题：构建失败（Build errors）与构建缓慢 / 资源耗尽（Slow builds）。你将学会如何逐个排查并修复 Git 仓库克隆阶段的典型错误，同时掌握从构建格式、依赖管理、conda 求解器到 autodoc 策略等多维度的性能优化手段，并了解当前构建资源限制与申请更多资源的正确途径。文中的所有结论均可在本仓库的官方文档、配置解析源码与构建调度源码中得到印证。

入口文档导读

本文对应仓库中的专题入口 docs/user/guides/troubleshooting/index.rst，该页面本身是 Read the Docs 故障排查系列指南的导航聚合页，指向两份核心子指南：

1. 构建错误排查指南：列出构建过程中最常见的错误信息及其解决方案，尤其集中在 Git 仓库克隆与认证环节；
2. 构建缓慢排查指南：总结拖慢构建速度的高频原因，即使当前没有性能问题，也建议提前熟悉。

两份子指南均引用共享的"如何参与完善故障排查文档"说明（见 docs/user/shared/contribute-to-troubleshooting.rst），鼓励用户贡献自己遇到的错误与解法。下面分别深入展开两份指南的全部内容。

一、构建错误排查：Git 阶段的四大典型报错

Read the Docs 的构建流程从克隆你的代码仓库开始（相关流程可参考 构建过程文档）。以下错误绝大多数发生在这一阶段。示例中以github.com为例，GitLab、Bitbucket 等其他 Git 提供商的报错信息与此类似。

1.fatal: could not read Username ... terminal prompts disabled

报错原文：

fatal: could not read Username for 'https://github.com': terminal prompts disabled

成因分析：

这个报错信息极具迷惑性，它并不是说你没有输入用户名。在 Read the Docs 的构建环境中，Git 交互式终端提示是被禁用的，因此任何需要人工输入的认证流程都会以该报错终止。它通常出现在以下两种情况：

• 仓库地址拼写错误或仓库已被删除：Read the Docs 无法通过给定的 URL 找到仓库，Git 尝试交互式询问凭据时被禁用，从而抛出此错误；
• 仓库由public改为private：如果你把仓库设为私有，却仍然在 Read the Docs 中使用https://形式的克隆地址，就会触发此错误。

解决方案：

1. 进入项目页面的Admin > Settings（管理 > 设置），核对仓库 URL 是否准确、仓库是否仍然存在；
2. 确认仓库可见性：私有仓库需要使用 Read the Docs 支持的私有仓库接入方式（需要对应的商业订阅套餐），不能依赖 https 匿名克隆。

2.error: pathspec 'main' did not match any file(s) known to git

报错原文：

error: pathspec 'main' did not match any file(s) known to git

成因分析：

说明 Read the Docs 试图检出的指定分支在 Git 仓库中不存在。常见诱因有两个：

• 仓库刚刚创建，还没有任何提交（commit）和分支；
• 仓库的默认分支改过名字。例如 GitHub 曾将默认分支从master迁移为main，如果项目配置仍停留在旧名称，就会报此错误。

解决方案：

进入Admin > Settings，将"默认分支（Default branch）"字段更新为仓库当前实际存在的分支名（如main），确保与仓库真实默认分支一致。

3.git@github.com: Permission denied (publickey)

报错原文：

git@github.com: Permission denied (publickey). fatal: Could not read from remote repository.

成因分析：

Read the Docs 使用 SSH 密钥认证去克隆私有仓库。该报错表示当前项目的公钥未被目标仓库、用户账户或组织授权，即 SSH 公钥没有作为deploy key（部署密钥）安装到你的 Git 提供商侧。

解决方案：

1. 进入项目页面的Admin > SSH Keys（管理 > SSH 密钥），复制其中展示的公钥内容；
2. 登录你的 Git 提供商，把该公钥添加为对应仓库的 deploy key。各平台操作入口分别为：GitHub 的Settings > Deploy keys、GitLab 的Settings > Repository、Bitbucket 的Admin > Access keys；
3. 确认添加时勾选了允许读写（write access）的权限选项（视你的构建需求而定，通常是 read-only 即可满足文档构建）。

4.ERROR: Repository not found.

报错原文：

ERROR: Repository not found. fatal: Could not read from remote repository.

成因分析：

该错误最常见的场景是：私有仓库上不再存在来自 Read the Docs 项目的公钥 deploy key（例如 deploy key 被删除、仓库被迁移、或者项目所属组织/账户发生变更），导致克隆认证失败。对于公开仓库而言该错误较为罕见——如果公开仓库也报此错，通常是因为配置中域名写错，或路径中遗漏了某个组成部分。

解决方案：

1. 进入Admin > SSH Keys，复制公钥内容；
2. 将该公钥重新安装为对应 Git 提供商的 deploy key（操作入口同上）；
3. 若为公开仓库，则重点检查仓库 URL 的域名与路径是否完整正确。

二、构建缓慢排查：六类资源瓶颈的定位与修复

Read the Docs 的每次构建都分配了有限的资源，其目的正是防止个别用户拖垮共享构建系统。当前构建资源限制可参考 Build resources 参考文档，核心限额包括：构建时长（社区/商业版默认 30 分钟、组织版 15 分钟，均可按需申请提升）、内存（7GB，商业版可升级）、并发构建数（组织版固定 2 个并发，商业版随套餐变化）以及磁盘存储（组织版 5GB 软限制）。

当构建长期卡在等待状态，或因为超出资源上限而被终止时，按以下顺序逐项排查通常能解决绝大多数问题。

1. 精简正在构建的文档格式（formats）

Read the Docs 除了默认的 HTML 外，还可以额外产出pdf、epub、htmlzip等离线格式。在htmlzip（HTML zip 打包格式）会占用可观的内存与构建时间，因此优先考虑禁用它，往往立竿见影。

在项目根目录的 .readthedocs.yaml 配置文件 中通过formats字段控制：

version: 2 build: os: "ubuntu-24.04" tools: python: "3.12" # 只构建 PDF 与 ePub，不再构建 htmlzip formats: - pdf - epub

源码级佐证：在仓库的 readthedocs/config/config.py 中，合法格式被限定为valid_formats = ["htmlzip", "pdf", "epub"]，且 validate_formats() 支持用关键字ALL表示"全部格式"。默认值为空列表[]，即默认不额外产出离线格式。而在构建调度侧，readthedocs/doc_builder/director.py 的build_htmlzip()方法会首先检查"htmlzip" not in self.data.config.formats，若配置中不含该格式则直接跳过打包步骤——这意味着只要从formats中移除htmlzip，整个 htmlzip 构建阶段就会在调度层面被整体跳过，节省的内存与时间非常可观。此外 readthedocs/builds/models.py 中的has_htmlzip字段还用于记录某个版本是否已产出过 zip 包，供下载页判断是否展示该格式入口。

2. 为文档构建单独维护精简的依赖清单

很多项目直接复用主项目的requirements.txt来构建文档，其中往往包含大量与文档无关的运行时依赖（Web 框架、数据库驱动、业务 SDK 等）。为文档构建单独创建一份精简的 requirements 文件，只保留 Sphinx 主题、扩展以及文档真正需要的包，可以显著缩短依赖安装时间并降低内存占用。

实践中建议：

• 在项目内新建docs/requirements.txt（或requirements-docs.txt），内容仅包含sphinx、文档主题、以及必要扩展；
• 在 .readthedocs.yaml 中通过python.install指向该文件：

version: 2 build: os: "ubuntu-24.04" tools: python: "3.12" python: install: - requirements: docs/requirements.txt

同时注意依赖解析阶段本身也消耗资源：仓库在 readthedocs/doc_builder/python_environments.py 中实现了基于虚拟环境的依赖安装流程，依赖项越多，pip 求解与下载的耗时越长，精简清单是投入产出比最高的优化之一。

3. 用 mamba 替代 conda，加速依赖求解

如果你必须使用 conda 包来构建文档（例如某些科学计算文档依赖 conda 分发的二进制包），那么你会遇到一个已知问题：当启用conda-forge频道时，conda 的依赖求解器会消耗大量内存并产生很长的求解时间——这源于 conda-forge 中软件包数量极其庞大。

解决方案：让 Read the Docs 使用 mamba 作为 conda 的替代品。mamba 是 conda 的即插即用替代实现，求解速度明显更快，且依赖求解过程的内存占用更低。配置方式见 conda 使用指南 的 "Making builds faster with mamba" 一节：在 .readthedocs.yaml 中把 Python 工具指定为miniconda系列即可：

version: 2 build: os: "ubuntu-24.04" tools: python: "miniconda3-3.12-24.9" conda: environment: environment.yml

其中build.tools.python的取值决定了 Read the Docs 将使用 mamba 作为 conda 环境的求解器，conda.environment指向你的environment.yml。如果希望完全避开defaults频道，可以在environment.yml的 channels 列表中用nodefaults替换defaults。

4. 用静态方式生成 Python 模块 API 文档

如果你的文档使用sphinx.ext.autodoc来生成 Python 模块的 API 参考，那意味着每次构建都必须安装这些模块的全部依赖（否则 import 会失败），这通常是文档构建内存与带宽开销的大头。

解决方案：改用 sphinx-autoapi 这类静态 API 生成扩展。sphinx-autoapi 不执行模块代码，而是通过静态分析源码结构来生成 API 文档，输出结果与 autodoc 基本一致，却能大幅降低构建所需的内存与带宽——因为不再需要为文档构建安装整套业务依赖。如果你的项目恰好属于"文档依赖很重、只为生成 API 页"的场景，这是收益最大的一项改造。

5. 申请更多构建资源（按项目提升配额）

如果完成上述优化后构建仍然超限，Read the Docs 支持按项目提升构建限额。官方给出的途径是：发送邮件至support@readthedocs.org，并提供充分的理由说明你的文档为何需要更多资源（例如大型单体文档、复杂的 API 站点）。

根据 Build resources 参考文档，社区/商业版默认 30 分钟构建时间与 7GB 内存都是**可升级（upgradable）**的；组织版则固定为 15 分钟构建时间、7GB 内存、2 个并发构建与 5GB 磁盘软限制。对于频繁触及资源上限的团队，也可以评估升级到具有额外构建资源的商业套餐。

三、排查方法论与源码依据汇总

四、实践建议：建立一套可复用的构建健康基线

综合两份子指南与源码实现，推荐按以下顺序建立你的构建健康基线：

1. 先看报错类型：凡是 Git 阶段报错，优先核对Admin > Settings中的仓库 URL、默认分支，以及Admin > SSH Keys中的 deploy key 是否有效——这是克隆阶段四大报错的统一排查路径；
2. 再砍格式：在 .readthedocs.yaml 中移除htmlzip，并确认formats列表只保留真正需要的pdf/epub，该改动会在 director.py 的调度层直接跳过打包流程；
3. 接着砍依赖：为文档单独维护精简依赖清单，必要时用 mamba 替换 conda 求解器，用 sphinx-autoapi 替换 autodoc，这三步能覆盖绝大多数"构建慢"根因；
4. 最后申请配额：若问题依旧，再依据 构建资源限制 发送邮件说明理由申请按项目提升资源，而不是盲目加依赖或加格式。

值得一提的是，仓库中的配置解析逻辑为formats提供了强约束：非法格式（如拼写错误的格式名）会在 validate_formats() 阶段直接抛出校验错误，相关行为有对应的单元测试覆盖（见 readthedocs/config/tests/test_config.py），因此在写配置文件时可以放心依赖其严格的格式校验。按照上述基线逐项执行，绝大多数构建失败与超时问题都能在十分钟内定位并解决。

• 后端
• 文档