ReadTheDocs构建未生成index.html文件问题求助

云原生阿岚

2026-6-25

问题

之前能正常构建的文档，近期重新构建时弹出报错：

Error
Your documentation did not generate an index.html at its root directory. This is required for documentation serving at the root URL for this version.

对应的.readthedocs.yaml配置如下：

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

# Build documentation in the docs/api directory with Sphinx
sphinx:
  builder: html
  configuration: docs/api/conf.py
  # TODO: needs dropping of additional customizations
  fail_on_warning: false

# Build docs in additional formats such as PDF and ePub
formats: all

# Specify dependencies to enable reproducible builds:
# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
  install:
    - requirements: packaging/pip_requirements_minimal.txt
    - method: pip
      path: ./packaging/

解决方法

调整Sphinx输出路径：默认Sphinx会把HTML产物放到docs/api/_build/html，但Read the Docs要求在构建根目录找到index.html。打开docs/api/conf.py，添加或修改以下配置，让产物生成到项目根目录的_build/html下：
```
html_output_dir = "../_build/html"
```
确认主文档配置：检查docs/api/conf.py里的root_doc设置，确保它指向你的主文档文件（比如index，对应index.rst或index.md）。如果主文档文件名不是index开头，Sphinx不会自动生成根目录的index.html。
本地预构建排查：在本地执行sphinx-build -b html docs/api docs/api/_build/html，查看产物目录里有没有index.html，路径是否符合要求。如果本地构建也出问题，先在本地搞定Sphinx配置和文档结构的问题。
查看构建日志：去Read the Docs的构建详情页看完整日志，排查有没有Sphinx构建时的警告或错误，比如依赖缺失、主文档找不到等，这些都可能导致index.html没生成。