VSCode需rust-analyzer插件+正确安装的Rust工具链才能获得Rust开发能力；缺任一环会报“No Rust project detected”或卡在“Loading…”。

VSCode 本身不内置 Rust 支持，必须通过 rust-analyzer 插件 + 正确安装的 Rust 工具链才能获得可用的代码补全、跳转和诊断能力；缺任意一环，rust-analyzer 就会报 “No Rust project detected” 或持续显示 “Loading…”。

确认 rustc 和 cargo 已正确安装并可用

这是所有后续配置的前提。很多人卡在第一步，却以为是插件问题。

• 终端运行 rustc --version 和 cargo --version，必须能输出版本号（如 rustc 1.80.1）；若提示 command not found，请先用 rustup install stable && rustup default stable 安装
• 确保 $HOME/.cargo/bin（Linux/macOS）或 %USERPROFILE%.cargoin（Windows）已加入系统 PATH —— VSCode 启动方式会影响环境变量继承：从桌面图标启动可能不加载 shell 的 PATH，建议从终端执行 code . 打开项目
• 检查 cargo metadata --no-deps --format-version 1 是否能成功执行；失败常因 Cargo.toml 格式错误或 workspace 配置异常，rust-analyzer 依赖此命令获取项目结构

安装并启用 rust-analyzer（不是 Rust 插件）

VSCode 商店中名为 “Rust”（由 rust-lang 官方维护）的插件早已弃用，它只提供基础语法高亮，不带 LSP 功能；真正起作用的是 rust-analyzer。

VSCode

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

下载

• 在扩展市场搜索 rust-analyzer，安装由 matklad 发布的官方版本（图标为蓝色原子结构）
• 禁用旧的 “Rust” 插件（否则可能冲突，导致 rust-analyzer 不自动激活）
• 打开一个含 Cargo.toml 的目录后，状态栏右下角应显示 rust-analyzer 并有进度条；若长期卡在 “Loading…”，用 Ctrl+Shift+P → 输入 Rust Analyzer: Reload Workspace 手动触发，再看输出面板中 Rust Analyzer 日志是否有 project model loaded

必要时手动指定 rust-analyzer 的 rustc 位置

多工具链（如 nightly + stable）、WSL 与 Windows 混用、或自定义 rustup 安装路径时，rust-analyzer 可能找不到正确的 rustc，表现为无法解析标准库类型（如 String 报 unresolved）。

• 打开 VSCode 设置（Ctrl+,），搜索 rust-analyzer server path，留空即使用自动下载的服务器；但若需绑定特定 toolchain，可设置 rust-analyzer.rustcSource 为 discover（默认）或 from_sysroot
• 更常见的是设置 rust-analyzer.cargo.loadOutDirsFromCheck 为 true，让其通过 cargo check 推导 target 目录，避免因 target/ 权限或路径异常导致构建信息缺失
• 如用 WSL，确保 VSCode 是通过 WSL 窗口打开（底部状态栏显示 WSL: Ubuntu），而非 Windows 版本直接访问 \wsl$ 路径 —— 后者会导致 rust-analyzer 进程运行在 Windows 上，无法调用 WSL 中的 cargo

调试配置：launch.json 必须用 cargo 启动器而非直接调用二进制

直接配置 program 指向 target/debug/my_project 通常失败：缺少环境变量、无法处理 #[cfg(test)]、且不支持 cargo run 的参数传递（如 -- -v）。

• 在项目根目录创建 .vscode/launch.json，使用 type: "cppdbg" 是错的；应选 type: "cargo"（需先安装 CodeLLDB 或 cortex-debug？不，cargo 类型由 rust-analyzer 提供）—— 实际上，VSCode Rust 调试依赖 CodeLLDB 插件 + cargo 配置组合
• 推荐最小可行配置：

  {
    "version": "0.2.0",
    "configurations": [
      {
        "type": "lldb",
        "request": "launch",
        "name": "Debug",
        "cargo": {
          "args": ["build", "--bin", "main"],
          "filter": { "name": "main", "kind": "bin" }
        },
        "args": [],
        "env": {}
      }
    ]
  }

  其中 cargo.args 触发构建，cargo.filter 指定要调试的 binary 名称（对应 src/main.rs 或 src/bin/*.rs）
• 若调试时断点不命中，检查是否启用了 debug = true（在 Cargo.toml 的 [profile.dev] 下确认）；release 模式默认关闭 debug info

最易被忽略的是：rust-analyzer 的配置项分散在 VSCode 设置、rust-project.json（极少用）、以及项目级 .rust-analyzer.toml 中；后者可覆盖全局设置，比如禁用某 crate 的代码检查（checkOnSave.overrideCommand），但一旦存在语法错误，整个文件的语义分析就会静默失效 —— 表现为补全消失、类型提示变灰，此时先删掉 .rust-analyzer.toml 排查。