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（蓝色原子图标，唯一推荐）。它们不能共存。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 禁用或卸载 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 没被正确识别、或者旧插件还在后台抢资源**。