必须先验证rustc和cargo在系统终端中可执行，否则rust-analyzer会卡在“loading...”；需在全新终端运行rustc --version和cargo --version均返回版本号，且path包含~/.cargo/bin（macos/linux）或%userprofile%.cargo\bin（windows）。
VSCode装完插件后，Rust编译工具链还没真正就位——rustc 和 cargo 必须在终端里能直接调用，否则 rust-analyzer 会一直显示“Rust (loading...)”或报错“command not found”。
验证 rustc 和 cargo 是否真可用
别信安装脚本的“Done”提示，也别只在 VSCode 终端里试。打开一个全新的系统终端（macOS/Linux 用 Terminal，Windows 用 PowerShell 或 CMD），执行：
rustc --version<br>cargo --version
两个命令都必须返回类似 rustc 1.75.0 和 cargo 1.75.0 的结果，版本号一致才算过关。常见失败现象：
-
command not found: rustc—— 说明~/.cargo/bin（macOS/Linux）或%USERPROFILE%\.cargo\bin（Windows）没进 PATH - 只返回
cargo但rustc报错 —— rustup 安装中途失败，或选错了工具链（比如 Windows 上误选 GNU 而没装 MinGW）
修复方法：
- macOS/Linux：运行
source $HOME/.cargo/env，再把这行加到~/.zshrc或~/.bash_profile - Windows：重启终端，或手动把
%USERPROFILE%\.cargo\bin加进系统环境变量 PATH
rust-analyzer 为什么卡在 loading 状态
即使 cargo --version 成功，rust-analyzer 仍可能不工作，原因通常是它找不到项目上下文。关键点：
- 必须从包含
Cargo.toml的目录启动 VSCode：cd my-project && code .，而不是在子目录里开（如cd src && code .） - 如果是 workspace 项目，根目录必须有
Cargo.toml，且内容至少含[workspace]声明 - rust-analyzer 默认只检查 lib/bin target，不扫 test 文件；要让它处理
#[cfg(test)]，得在 VSCode 设置里加配置：rust-analyzer.cargo.extraArgs设为["--all-targets"]
Windows 用户特别注意链接器问题
rustc 编译通过，但 cargo build 报 linker 错误（如 “linker `link.exe` not found”），这不是 rust-analyzer 的锅，是缺少 C++ 构建工具：
- 必须安装
Build Tools for Visual Studio，勾选 “Desktop development with C++” 工作负载 - 不要用普通 CMD 或 PowerShell 启动 VSCode —— 改用 “Developer Command Prompt for VS 2022”，它自带完整环境变量
- 验证方式：在 Developer Command Prompt 里运行
cl.exe，有输出即表示 MSVC 就绪
镜像和组件补全不是可选项
国内用户常卡在 rustup 组件下载（尤其是 rust-src 或 rust-docs），导致 rust-analyzer 无法跳转标准库源码：
- 立即设置镜像源：
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup（Linux/macOS） - 补装必要组件：
rustup component add rust-src rust-docs，否则 hover 类型时看不到文档，Go to Definition会失败 - 想用 clippy 检查风格？运行
rustup component add clippy，再在 VSCode 设置里把rust-analyzer.check.command改成clippy
最易被忽略的是：rust-analyzer 不依赖你装了什么插件，只认你终端里 cargo 能否正常执行、项目结构是否合规、以及 rust-src 是否存在。其他所有配置都是锦上添花，这三样缺一不可。
