build.rs 卡住会导致 cargo check 和 rust-analyzer 无响应，因其必须执行 build.rs 才能获取 OUT_DIR、cfg 标志等元信息；阻塞操作如未超时的 git 调用、网络请求或不存在路径的 fs 读取会直接挂起整个检查流程。
build.rs 卡住时 cargo check 也会挂，别只盯着 rust-analyzer
rust-analyzer 默认调用 cargo check 做静态分析，但只要项目里有 build.rs，它就会默默执行这个脚本——哪怕你只是想看个类型提示。一旦 build.rs 里写了阻塞操作（比如死循环、无限等待网络、或调用未响应的外部命令），cargo check 就会卡在“Loading…”状态，连带 rust-analyzer 整体无响应。
这不是 rust-analyzer 的 bug，是 Cargo 的行为：它必须运行 build.rs 才能确定 OUT_DIR、cfg 标志和生成的头文件路径，否则无法安全解析依赖项。
- 现象：状态栏右下角长期显示 “Rust (rust-analyzer)” + 转圈，
Output → Rust Analyzer日志停在running build script或building [package] - 验证方式：在 VSCode 内置终端（
Ctrl+`）手动运行cargo check --verbose，观察是否卡在Running build script这一行 - 临时绕过：在
Cargo.toml中加build = false（仅用于诊断，勿提交）；或把build.rs重命名为build.rs.bak看 rust-analyzer 是否立刻恢复
build.rs 里哪些写法最容易让 cargo check 卡死
很多 build.rs 为了“保险”会做同步 IO 或外部命令调用，但在 cargo check 场景下毫无必要，且极易出问题。
-
std::process::Command::new("git").args(&["rev-parse", "HEAD"]).output()：如果当前目录不是 git 仓库，或 git 正在锁库（比如另一终端刚执行了git pull），就会阻塞数秒甚至更久 -
std::fs::read_to_string("./config.json")：路径不存在时 panic，但 rust-analyzer 不捕获 panic，直接中断整个检查流程 -
reqwest::blocking::get("https://api.example.com/version")：网络请求超时默认 30 秒，cargo check 完全等不起 -
println!("cargo:rerun-if-changed=src/...引用了不存在的路径：Cargo 不报错，但某些版本会静默 hang
如何让 build.rs 对 cargo check 友好
核心原则：cargo check 不需要真实构建产物，只需要快速返回“没变化”。所有耗时、IO、网络操作都该被跳过。
- 用
std::env::var_os("CARGO_CMD") == Some("check".into())判断当前是否为 check 模式（注意：此环境变量非官方保证，但 rustc 1.79+ 和 cargo 1.79+ 确实提供） - 更可靠的方式是检查
std::env::var("PROFILE")：若值为"debug"且std::env::var("CARGO_FEATURES").is_ok()，说明大概率是正常 build；若PROFILE为空或OPT_LEVEL为""，可视为 check 场景 - 把耗时逻辑包进
if !std::env::var("CARGO_CHECK").is_ok() { /* real work */ }，并在顶部加println!("cargo:rerun-if-env-changed=CARGO_CHECK"); - 所有
fs操作加std::fs::metadata(...).is_ok()预检，失败时直接return，不 panic
VSCode 里怎么快速定位是 build.rs 导致卡死
别先重装插件或清缓存——90% 的“rust-analyzer 卡死”背后是 build.rs 在拖后腿，而 VSCode 并不提示这点。
- 打开
Output → Rust Analyzer面板，搜索build script或running，看最后一条日志是不是停在这儿 - 在终端运行
cargo check --message-format=json | jq 'select(.reason == "compiler-message")'（需装jq），若无输出且进程不退出，基本锁定build.rs - 禁用
rust-analyzer.cargo.loadOutDirsFromCheck设置（设为false），这会让 rust-analyzer 绕过build.rs输出路径读取，有时能恢复响应——但代价是宏展开和include!路径可能失效 - 如果项目含 workspace，检查每个 crate 的
build.rs：卡死可能来自某个子 crate，而非主 crate
build.rs 的健壮性常被忽略，但它实际是整个 Cargo 工作流的入口阀门。一次阻塞，整条链路就断了——不是 rust-analyzer 太慢，是你给它喂了一个停不下来的脚本。
