如何在ReadTheDocs构建系统中使用Ubuntu 20.04的testing镜像？

算力阿峰

2026-10-17

可行操作方案

优先使用官方正式支持的显式OS指定配置，替代旧的image: testing写法
Read the Docs 现已支持在v2版配置文件中直接指定操作系统版本，无需使用测试镜像标签，正确配置示例如下：
```
version: 2

build:
  os: ubuntu-20.04
  tools:
    python: "3.9" # 可根据你的需求替换为3.8~3.11的支持版本
```
该配置会直接调用官方Ubuntu 20.04正式构建镜像，libc6版本默认是2.31，完全满足PySide6的依赖要求。
检查后台配置优先级，避免配置被覆盖
如果你仍然坚持使用testing镜像标签，需要进入项目后台管理的「Advanced Settings」页面，确认「Use a configuration file」选项已开启，同时取消所有手动指定默认构建镜像的勾选，避免后台全局配置优先级高于本地.readthedocs.yaml配置导致设置不生效。
配置验证方法
你可以在构建配置中添加前置检查命令，确认环境是否符合预期：
```
build:
  os: ubuntu-20.04
  tools:
    python: "3.9"
  jobs:
    pre_install:
      - lsb_release -a
      - apt policy libc6
```
触发构建后在pre_install阶段的日志中即可查看当前系统版本和libc6版本，确认配置是否生效。