GitHub Actions中cargo doc构建Rust文档失败问题求助

概述 #

在使用GitHub Actions为protocol-substrate仓库的fork版本构建Rust文档时出现构建异常，对应仓库、报错的Action运行记录、使用的工作流文件均可在GitHub公开页面查询到。经测试，上游原仓库执行相同构建操作时也会触发完全一致的错误。

本地环境执行cargo doc --release --no-deps --open可正常完成文档构建，但CI环境下执行相同命令会直接失败。

已尝试的排查方案 #

• 使用--exclude参数排除最先报错的问题包，但排除后下一个包会继续触发同类报错：最先报错的包为webb-client，排除后报错包变更为webb-primitives
• 执行cargo doc命令前先拉取仓库所有子模块
• 执行cargo doc命令前先运行cargo build --release完成全量预构建
• 执行文档构建命令时添加--all-features参数启用所有crate特性

检索到的相关已知问题 #

• Rust官方代码仓库已收录同类rustdoc内部编译错误问题，报错特征与本次问题完全匹配

CI环境报错日志 #

thread 'rustc' panicked at 'no entry found for key', src/librustdoc/passes/collect_intra_doc_links.rs:930:16
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
error: internal compiler error: unexpected panic
error: Unrecognized option: 'crate-version'
error: could not document `webb-primitives`

问题根因 #

该报错属于Rust编译器内部错误（ICE），由两个独立问题共同触发：

1. CI环境默认使用的Rust工具链版本与本地环境不一致，命中了rustdoc 1.62版本前后collect_intra_doc_links pass的已知并发bug，和检索到的官方已知问题完全对应
2. CI环境中cargo与rustc/rustdoc版本不匹配：crate-version是新版cargo调用rustdoc时传入的参数，若rustdoc版本过低会无法识别该参数直接报错

修复方案 #

• 固定CI与本地的Rust工具链版本完全一致：在仓库根目录新增rust-toolchain.toml文件明确指定工具链版本，或在CI构建步骤中通过rustup override set <本地对应的版本号>强制指定版本，避免CI默认拉取的beta/nightly版本触发未修复的已知bug
• 保证CI环境中cargo与rustc版本同源，禁止单独升级cargo或rustc组件，使用rustup update统一更新工具链即可
• 临时规避方案：执行cargo doc时追加-j 1参数禁用并行构建，可绕过部分场景下并发触发的文档链接收集bug

内容的提问来源于stack exchange，提问作者Dutt