ReadTheDocs构建依赖Maturin的Python项目时Cargo锁文件版本报错

核心问题是ReadTheDocs默认环境中的Cargo版本过低，无法识别Rust crate的Cargo.lock文件（版本4），进而导致maturin构建失败。

解决步骤 #

1. 在ReadTheDocs配置中指定Rust工具链版本 #

在项目的.readthedocs.yaml配置文件中，添加Rust工具链的配置，指定使用兼容lockfile版本4的稳定版：

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
    rust: stable

2. 手动更新Cargo（备选方案） #

如果配置指定工具链不生效，可在构建命令中手动更新Cargo：
在.readthedocs.yaml的build.commands中添加：

build:
  commands:
    - curl https://sh.rustup.rs -sSf | sh -s -- -y
    - source $HOME/.cargo/env
    - pip install -r requirements.txt

3. 降级Cargo.lock版本（临时方案） #

若无法更新环境中的Rust工具链，可在本地生成旧版本兼容的lockfile：

# 安装支持lockfile版本3的Cargo版本
rustup install 1.68.0
rustup default 1.68.0
# 重新生成兼容的lockfile
cargo generate-lockfile --lockfile-version 3

将新生成的Cargo.lock提交到仓库后，旧版Cargo即可正常识别。

前置验证 #

本地先执行cargo build确认Rust crate可正常编译，再推送代码触发ReadTheDocs重新构建。

内容的提问来源于stack exchange，提问作者Frank C.