rust-analyzer 能用的前提是：1. vscode 打开含 cargo.toml 的目录；2. 终端可运行 cargo --version 和 rustc --version；3. 禁用 rust-lang.rust 插件。任一不满足则卡在 loading 或不显示。

rust-analyzer 是唯一能用的 Rust 语言服务器，装错插件或 PATH 没生效，VS Code 就只是个高亮编辑器——连 String 都会标红报 unresolved。

确认 rustc 和 cargo 已在 PATH 中且可执行

这是整个配置的地基。VS Code 启动时若没继承到 $HOME/.cargo/bin（macOS/Linux）或 %USERPROFILE%\.cargo\bin（Windows），rust-analyzer 就无法调用 cargo metadata，直接卡在 “Loading…” 或报 No Rust project detected。

• 终端里运行 cargo --version 和 rustc --version，必须都输出版本号（如 rustc 1.80.1）
• VS Code 集成终端里也得能跑通这两个命令；如果终端可以、VS Code 里不行，说明启动方式没加载 shell 环境变量
• macOS/Linux：别从桌面图标启动 VS Code，改用终端执行 code .；或手动在设置中补全 terminal.integrated.env.macos 的 PATH
• Windows：检查系统环境变量是否含 %USERPROFILE%\.cargo\bin；用 Scoop 安装的还要加 %USERPROFILE%\scoop\shims

只装 rust-analyzer，禁用所有叫 “Rust” 的旧插件

VS Code 商店搜 “Rust” 会出现两个高星插件：rust-lang.rust（红黑熊图标，已弃用）和 matklad.rust-analyzer（蓝色原子结构，当前唯一推荐）。前者走 RLS 协议，不支持 async/await、宏展开，且与 rust-analyzer 冲突。

VSCode

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

下载

• 卸载或禁用 rust-lang.rust 和任何带 rls 字样的插件
• 安装 rust-analyzer 后重启 VS Code
• 打开一个含 Cargo.toml 的目录（不是子文件夹），状态栏右下角应出现 rust-analyzer 进度条
• 若长期卡住，按 Ctrl+Shift+P → 输入 Rust Analyzer: Reload Workspace 手动触发，并看 Output 面板中 Rust Analyzer 日志是否出现 project model loaded

项目级 .vscode/settings.json 必配项

全局设置容易在多项目间互相干扰，尤其涉及不同 edition、feature 或 workspace 时。推荐在项目根目录建 .vscode/settings.json：

{
  "rust-analyzer.cargo.loadOutDirsFromCheck": true,
  "rust-analyzer.procMacro.enable": true,
  "rust-analyzer.checkOnSave.command": "check"
}

• "rust-analyzer.cargo.loadOutDirsFromCheck": true：让插件通过 cargo check 推导 target/ 路径，避免因路径异常或权限导致构建信息缺失
• "rust-analyzer.procMacro.enable": true：开启宏展开支持（如 #[derive(Serialize)]、sqlx::query!）
• "rust-analyzer.checkOnSave.command": "check"：比默认的 clippy 更轻量，防止保存时卡顿；大型项目还可加 "rust-analyzer.cargo.autoreload": false 避免频繁重载

遇到 unresolved import 却能编译通过？先别动 target/

cargo check 成功但 rust-analyzer 报大量未解析符号，最常见原因是手动执行了 rm -rf target/。插件依赖 target/ 下的 rustc 产物生成语义索引，删掉就等于清空它的“大脑”。

• 开发中尽量避免 rm -rf target/；需要清理时用 cargo clean --release 或仅删 target/debug/deps
• 误删后不用重装，执行 Rust Analyzer: Reload Workspace 即可重建索引（耗时取决于项目大小）
• 若项目用 no_std 或自定义 sysroot，需在项目根加 rust-project.json，否则标准库类型无法跳转

真正卡住的地方往往不是插件装没装，而是 cargo 命令能不能被 VS Code 的集成终端看见，以及你打开的到底是不是 Cargo 工作区根目录。这两点没对，后面所有配置都白搭。