Rust 1.99 stable 版本升级前的工具链检查清单

我在准备 Rust 1.99 stable 升级时，最先踩到的坑不是编译错误，而是“stable”这个名字让人误以为所有环境都已经切到了同一个版本。Rust 1.99.0 的稳定版公告发布于 2026 年 10 月 1 日，随后 1.99.1 在 10 月 15 日修复了几个回归，所以升级前的第一项检查不是直接执行更新，而是先确认目标版本和实际生效入口。

官方版本公告：https://blog.rust-lang.org/2026/10/01/Rust-1.99.0/

修复版公告：https://blog.rust-lang.org/2026/10/15/Rust-1.99.1/

如果项目没有必须锁定 1.99.0 的理由，检查清单应以 Rust 1.99.1 为目标：先盘点本机和 CI 的工具链选择来源，再核对项目声明、锁文件和目标平台，最后用显式版本做一轮可回滚检查。

先确认目标版本，再盘点实际工具链

Rust 1.99.0 是稳定版基线，但 1.99.1 是后续修复版。官方说明中，1.99.1 修复了部分目标缺少 wcslen、x86_64 FFI bool 返回值以及 macOS 上 rust-lld 加载 libLLVM 的问题。它们不一定会影响每个项目，却说明“升级到 stable”仍然需要把具体补丁版本写进记录。

我会先把下面四条命令的输出保存到升级记录里。命令只负责识别入口，不代表项目已经通过测试：

# 查看当前目录最终会采用哪个 rustup 工具链
rustup show

# 记录编译器、主机平台和提交信息
rustc --version --verbose

# 记录 Cargo 版本，避免只比较 rustc
cargo --version

# 检查是否存在会改变版本选择的环境变量
printenv RUSTUP_TOOLCHAIN

rustup show 是关键入口。rustup 的选择顺序会受到命令行显式指定、RUSTUP_TOOLCHAIN、目录覆盖、rust-toolchain.toml 和默认工具链影响；仓库里的固定文件还可能被父目录的设置或 CI 工作目录影响。图 1 用静态关系把这几层放在一起，方便定位“我更新了，但构建仍没变”的原因。

把项目支持边界写清楚

第二项检查是打开 Cargo.toml，确认 [package] 下的 rust-version。它表达的是项目支持的最低 Rust 版本，不是“开发机当前安装的版本”。如果项目暂时只想验证 1.99.1，不要为了跟随升级顺手把最低支持版本改成 1.99；只有当代码、依赖和发布策略都准备好时，才把它作为独立变更提交。

[package]
# rust-version 是项目承诺支持的最低工具链，不等于本机当前版本
name = "sample-service"
version = "0.4.0"
rust-version = "1.80"

# 若项目决定把开发分支固定到 1.99.1，可单独提交这个文件
[workspace.metadata.toolchain]
checked-with = "1.99.1"

接着确认 Cargo.lock 是否纳入版本控制。工具链升级本身不必然改变依赖解析，但 Cargo 版本、平台目标或依赖的最低 Rust 版本可能让构建表现不同。可以用机器可读的元数据确认 workspace 结构，并把命令放在 CI 的临时验证任务中：

# 只读取 workspace 和依赖解析信息，不修改 Cargo.lock
cargo +1.99.1 metadata --format-version 1 --no-deps

# 显式使用 1.99.1 做轻量检查，避免受默认 stable 影响
cargo +1.99.1 check --workspace --all-targets

这里的 +1.99.1 是 rustup 代理的显式工具链写法，目的在于让检查结果和“默认 stable 是什么”解耦。若项目包含多个目标平台，还要把每个 CI job 的 target、额外组件和链接器列出来；只在当前笔记本上通过，不能代替交叉编译或 Windows/macOS runner 的检查。

按风险分层切换，保留回滚点

我更倾向于把升级拆成三个小提交。第一步只安装并显式调用 1.99.1，不改默认值；第二步让 CI 增加一个 1.99.1 验证矩阵，观察各目标平台；第三步才决定是否更新 rust-toolchain.toml 或把默认 stable 切换过去。这样即使某个构建脚本、原生依赖或平台组件出现问题，也能快速回到上一条固定配置。

# 安装目标工具链，但不覆盖项目原有固定配置
rustup toolchain install 1.99.1

# 用显式版本执行格式化、检查和测试；失败时保留完整输出
cargo +1.99.1 fmt --all -- --check
cargo +1.99.1 check --workspace --all-targets
cargo +1.99.1 test --workspace

# 记录目标平台，避免只在宿主机上得出结论
rustup target list --installed

如果项目本来就用 rust-toolchain.toml 固定版本，可以在确认 CI 和本地都完成验证后再提交修改。文件的价值是把工具链意图带进仓库，但它也会让“在错误目录执行命令”变成隐蔽问题，所以升级记录中要保留实际目录、runner、target、组件和回滚提交。

我的最终检查清单

• 目标写的是 Rust 1.99.1，还是必须保留 1.99.0；理由是否记录清楚。
• rustup show、环境变量、目录覆盖和 rust-toolchain.toml 是否指向同一个预期。
• rust-version、Cargo.lock、feature、原生依赖和各 target 是否已盘点。
• CI 是否用 cargo +1.99.1 做过 workspace、全 target 和测试检查，并保存失败输出。
• 若要提交固定版本，是否有单独变更和明确回滚点。

这份清单的重点不是证明 Rust 1.99.1 对所有项目都“零风险”，而是把升级风险从一个模糊的版本动作拆成可追踪的入口、支持范围和平台矩阵。小项目可以只做前两层；有原生依赖、交叉编译或多 runner 的项目，则应把 CI 验证当成升级的一部分。

相关问题

只执行 rustup update stable 可以吗？

可以作为个人环境更新动作，但它不能替代项目级检查。正式升级前仍应确认当前目录的覆盖规则、项目的 rust-version、CI 目标平台和回滚方式。

为什么 rustc 已经是 1.99.1，Cargo 结果却不一致？

常见原因是命令不在同一个目录、环境变量或 rust-toolchain.toml 触发了不同的 rustup 入口，或者 CI 使用了另一个 runner。优先比较 rustup show、rustc --version --verbose 和 cargo --version 的同一份记录。