rust-analyzer 能用的前提是同时满足三点：打开含 cargo.toml 的目录、集成终端中 cargo/rustc 均可执行且输出版本号、禁用 rust-lang.rust 插件；任一不满足则卡在 loading 或不显示。
rust-analyzer 装上不等于能用，90% 的问题出在它根本没连上 cargo 和 rustc——不是插件装错了，是环境链路断了。状态栏卡在 Loading...、String 标红报 unresolved、跳转失效，全都是这个原因。
rust-analyzer 启动失败的三个硬性前提
它只在同时满足以下三点时才会真正启动：
- VSCode 打开的是含
Cargo.toml的目录（不是子文件夹，也不是单个.rs文件） - 集成终端里能直接运行
cargo --version和rustc --version，且都输出版本号 -
rust-lang.rust插件已被禁用或卸载（它和rust-analyzer冲突，共存必废）
任意一条不满足，右下角就只会显示 rust-analyzer (loading) 卡死，或压根不出现。别急着重装，先按这三条挨个核对。
VSCode 集成终端里 cargo 报 command not found 怎么办
这是“No Rust project detected”最常见原因。rust-analyzer 启动时会调用 cargo metadata 解析项目结构，命令都找不到，它连第一步都迈不出去。
- macOS/Linux：桌面图标启动的 VSCode 不加载
~/.zshrc或~/.bash_profile，$HOME/.cargo/bin就进不了PATH；改用终端执行code --new-window .打开项目 - Windows：检查系统环境变量是否包含
%USERPROFILE%\.cargo\bin；若用 Scoop 安装 rustup，还要加%USERPROFILE%\scoop\shims - 验证方式：在 VSCode 内置终端（
Ctrl+`）里运行cargo --version和rustc --version，两个都必须输出版本号 - “Reload Window” 不刷新环境变量——必须彻底退出 VSCode 再重开
为什么宏展开不工作、#[derive] 没提示
默认情况下 rust-analyzer.procMacro.enable 是 false，所有过程宏（如 serde 的 #[derive(Deserialize)]、sqlx::query!）都不会被解析，hover 看不到类型、Ctrl+Click 跳转失败、宏体内变量标红但编译通过。
- 必须在项目根目录的
.vscode/settings.json中显式启用："rust-analyzer.procMacro.enable": true - 仅开这一项还不够，还得配
"rust-analyzer.cargo.loadOutDirsFromCheck": true，否则宏展开后生成的新类型路径无法被定位 - 删过
target/或执行过cargo clean后，必须手动执行Rust Analyzer: Reload Workspace（不是重启 VSCode），否则索引仍指向已删除的产物文件
多 crate workspace 项目跳转失效
rust-analyzer 必须通过根目录的 Cargo.toml（含 [workspace] 块）一次性解析整个结构。如果打开的是子 crate 目录，或根 Cargo.toml 缺少 [workspace]，它就把每个 crate 当成孤立项目处理。
- 检查点：根目录
Cargo.toml是否有[workspace]，且members列表正确列出所有子 crate 路径（避免用通配符["crates/*"]，某些 rustup 版本不识别） - 子 crate 的
Cargo.toml中[lib]必须存在，且不能设proc-macro = true（前端 crate 不能是 proc-macro 类型） - 中文路径或空格路径会触发启动失败，临时改用纯英文路径验证
复杂点在于：rust-analyzer 的索引严重依赖 target/ 下的构建产物，而这些产物又受 cargo check 输出路径、toolchain 版本、workspace 成员声明顺序等多层影响——一旦某处错位，符号解析就断链，且错误表现往往不直观。调试时优先看 Output 面板中 Rust Analyzer 日志，关键线索常藏在 project model loaded 是否出现、以及 failed to run cargo metadata 这类提示里。
