rust-analyzer装上不等于能用，必须满足三项硬性前提：打开含Cargo.toml的目录、终端可运行cargo/rustc --version、禁用rust-lang.rust插件；任一不满足即卡在loading或报“No Rust project detected”。
rust-analyzer 不是装上就完事的插件，它必须和本地 cargo、rustc 工具链对齐，否则状态栏卡在 “Loading…”、跳转失效、类型标红（比如 String 报 unresolved）全是常态。核心问题从来不是插件没装，而是 VSCode 根本没“看见” Rust 工具链。
为什么 rust-analyzer 一直显示 “Loading…” 或报 “No Rust project detected”
它只认当前工作区根目录下的 Cargo.toml，不会向上递归找，也不会自动识别子 crate 目录。
- 打开项目时，确保终端 pwd 是含
Cargo.toml的目录，然后运行code .—— 不要双击图标、不要从文件管理器拖入单个.rs文件 - 多 crate workspace 项目，必须打开最外层根目录（即有
[workspace]的Cargo.toml所在目录），否则每个子 crate 都被当孤立项目处理 - 中文路径或空格路径会触发 rust-analyzer 启动失败，临时改用纯英文路径验证
- 按
Ctrl+Shift+P输入Rust Analyzer: Show Server Status，如果显示failed to start，说明连服务器进程都没起来，先别调设置，回头检查工具链
cargo 和 rustc 在终端能跑，但在 VSCode 里报 command not found
VSCode 启动方式决定它继承哪套环境变量。桌面图标启动通常不加载 shell 的 .zshrc 或 .profile，$HOME/.cargo/bin 就进不了 PATH。
- macOS/Linux：关闭 VSCode，从终端执行
code --new-window .（注意最后的点） - Windows：检查系统环境变量中是否包含
%USERPROFILE%\.cargo\bin；若用 Scoop 安装 rustup，还要加%USERPROFILE%\scoop\shims - 验证方式：在 VSCode 内置终端（
Ctrl+`）里运行cargo --version和rustc --version，两个都必须输出版本号 - 别信 “Reload Window”，它不刷新环境变量 —— 必须彻底退出 VSCode 再重开
装了 rust-analyzer 却和旧 “Rust” 插件冲突
VSCode 商店搜 “Rust” 会出现两个高权重插件：rust-lang.rust（红黑熊图标，已弃用）和 matklad.rust-analyzer（蓝色原子图标，唯一推荐）。它们不能共存。
- 禁用或卸载
rust-lang.rust—— 它走已归档的 RLS 协议，不支持宏展开、async/await，且会静默禁用rust-analyzer - 按
Ctrl+Shift+P输入Extensions: Show Enabled Extensions，确认rust-analyzer状态为“已启用” - 别装 “RLS”、“rust-client”、“rust-test-explorer” 这类过时扩展，它们只会干扰
项目能编译但 rust-analyzer 报大量 unresolved import / unresolved type
常见原因是手动删了 target/ 目录，或 cargo check 没成功生成语义产物，导致分析器无法建立索引。
- 避免执行
rm -rf target/—— 开发中频繁清理会打断 rust-analyzer 的缓存链 - 在项目根目录建
.vscode/settings.json，写入关键配置：{ "rust-analyzer.cargo.loadOutDirsFromCheck": true, "rust-analyzer.procMacro.enable": true, "rust-analyzer.checkOnSave.command": "check" } -
"loadOutDirsFromCheck": true让它通过cargo check输出反推构建路径，绕过target/权限或结构异常问题 -
"procMacro.enable": true是serde、sqlx等 derive 宏展开的前提，关了就看不到字段补全
rust-analyzer 的真实工作流依赖 cargo metadata、cargo check 和本地 target/ 目录三者联动。任何一环断开，它就退化成语法高亮器。最容易被忽略的是：**你看到的“插件问题”，90% 是 PATH 没继承、Cargo.toml 没被正确识别、或者旧插件还在后台抢资源**。 
