Rust初学者常见问题总结:让你顺利写下你的第一个“Hello Rust！“

一、编译时需要C语言连接器

error: linker `link.exe` not found
  |
  = note: program not found

note: the msvc targets depend on the msvc linker but `link.exe` was not found

note: please ensure that Visual Studio 2017 or later, or Build Tools for Visual Studio were installed with the Visual C++ option.

note: VS Code is a different product, and is not sufficient.

error: aborting due to 1 previous error

这个错误是因为 Rust 编译时需要调用 Windows 的 C 语言链接器 link.exe，但你的电脑上没安装这个工具。别慌，这是 Windows 系统学 Rust 时的常见问题，按下面的步骤操作就能解决：
问题原因
Rust 编译程序时，除了自身的编译器，还需要系统提供的 “链接器”（把编译后的代码组装成可执行文件的工具）。在 Windows 上，Rust 默认用微软的 link.exe（属于 Visual Studio 工具链），如果没安装，就会报这个错。
解决方法：安装 Visual Studio 构建工具
不需要装完整的 Visual Studio（太大了），只装 “构建工具” 就行，步骤如下：

1. 下载安装工具打开微软官网下载页面：https://visualstudio.microsoft.***/zh-hans/free-developer-offers/拉到最下面，找到 “Visual Studio 生成工具”，点 “下载”（文件很小，大概 1MB 左右）。
2. 安装时选对组件运行下载的 vs_BuildTools.exe，会弹出安装界面：

• 在左侧勾选 “桌面开发 with C++”（中文界面可能叫 “使用 C++ 的桌面开发”）
• 不用勾选其他额外组件，默认的 “MSVC 生成工具”“Windows SDK” 就是我们需要的
• 点右下角 “安装”，等待完成（大概需要下载 1-2GB 内容，取决于网络）。

3. 重启电脑安装完成后，一定要重启电脑！让系统识别到新安装的 link.exe 路径。

验证是否解决
重启后，打开新的终端（一定要新打开，确保环境变量生效），进入你的 Rust 项目，再次运行：

cargo run

如果能正常编译并输出 “Hello, Rust!”，就说明问题解决了。
补充：如果不想装 Visual Studio 工具链
还有一种方案是改用 GNU 链接器（适合习惯 Linux 工具链的用户），但步骤稍复杂：

1. 在终端运行 rustup toolchain install stable-x86_64-pc-windows-gnu
2. 再运行 rustup default stable-x86_64-pc-windows-gnu
3. 下载 MinGW-w64（GNU 工具链）并配置环境变量（新手不太推荐，容易踩其他坑）。

所以还是推荐第一种方案，虽然下载量大点，但一步到位，后续开发其他 C/C++ 相关程序也能用。按步骤来，很快就能搞定～

二、使用Cargo创建新项目

Creating binary (application) `XXX` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

看到这个提示说明你已经成功用 cargo new xxx 创建了一个 Rust 二进制项目（也就是可执行程序项目），“Creating binary (application) xxx package” 是 Cargo 的成功反馈，完全不用慌～

接下来我带你快速过一遍这个项目的关键信息，帮你知道下一步该做什么：

1. 先搞懂：这个项目里有什么？
   你打开刚创建的 xxx 文件夹，会看到两个核心内容：

• src 文件夹：里面有个 main.rs 文件，这是你写代码的地方，默认已经帮你生成了 “Hello World” 代码：

fn main() {
    println!("Hello, world!");
}

Cargo.toml 文件：这是项目的 “配置清单”，记录了项目名称（xxx）、版本、依赖库等信息，默认内容长这样：

[package]
name = "foo"          # 项目名
version = "0.1.0"     # 项目版本
edition = "2024"      # 使用的Rust版本（目前主流是2021）

[dependencies]        # 依赖库区域，现在是空的，以后加第三方库用

1. 下一步：运行这个项目
   现在你可以直接在终端里运行这个默认项目，体验一下完整流程：
2. 先进入项目文件夹（终端里输入，注意把路径换成你自己的 xxx 文件夹路径）：

cd 你的文件夹路径/xxx

3. 运行项目（用 Cargo 的命令，会自动编译 + 执行）：

cargo run

第一次运行会看到 “***piling foo v0.1.0” 的编译提示，最后会输出 Hello, world! —— 这就说明项目能正常工作啦～
4. 再学两个常用操作
除了 cargo run，这两个命令你以后也会经常用：

• cargo check：快速检查代码有没有语法错误，不生成可执行文件。比如你写了一段代码，想先看看有没有错，就用这个命令，比 cargo run 快很多。
• cargo build：只编译项目，不运行。编译好的可执行文件会存在 xxx/target/debug/ 文件夹里（Windows 是 xxx.exe，Mac/Linux 是 xxx），以后想直接运行编译好的程序，双击这个文件就行。

5. 后续：开始修改代码
   现在你可以尝试修改 src/main.rs 里的代码，比如把打印内容改成自己的话：

fn main() {
    println!("我的第一个Rust项目！");
    println!("项目名是xxx～");
}

改完后再运行 cargo run，就能看到新的输出了。
如果后续想加功能（比如读文件、做计算），直接在 main.rs 里写就行；如果需要用第三方库（比如做网页开发、处理 JSON），就把库的名字和版本写到 Cargo.toml 的 [dependencies] 下面，Cargo 会自动帮你下载安装～

三、Rust工具链不对应

error: linking with `x86_64-w64-mingw32-g***` failed: exit code: 1
  |
  = note: "x86_64-w64-mingw32-g***" "-fno-use-linker-plugin" "-Wl,--dynamicbase" "-Wl,--disable-auto-image-base" "-m64" "-Wl,--high-entropy-va" "<sysroot>\\lib\\rustlib\\x86_64-pc-windows-gnu\\lib\\self-contained\\crt2.o" "<sysroot>\\lib\\rustlib\\x86_64-pc-windows-gnu\\lib\\rsbegin.o" "C:\\Users\\李宇\\AppData\\Local\\Temp\\rustcGBxJu5\\symbols.o" "<25 object files omitted>" "-Wl,-Bstatic" "<sysroot>\\lib\\rustlib\\x86_64-pc-windows-gnu\\lib/{libstd-*,libpanic_unwind-*,libobject-*,libmemchr-*,libaddr2line-*,libgimli-*,libcfg_if-*,libwindows_targets-*,librustc_demangle-*,libstd_detect-*,libhashbrown-*,librustc_std_workspace_alloc-*,libminiz_oxide-*,libadler2-*,libunwind-*,liblibc-*,librustc_std_workspace_core-*,liballoc-*,libcore-*,lib***piler_builtins-*}.rlib" "-Wl,-Bdynamic" "-lkernel32" "-lkernel32" "-lkernel32" "-lntdll" "-luserenv" "-lws2_32" "-ldbghelp" "-lg***_eh" "-l:libpthread.a" "-lmsvcrt" "-lmingwex" "-lmingw32" "-lg***" "-lmsvcrt" "-lmingwex" "-luser32" "-lkernel32" "-Wl,--nx***pat" "-nostartfiles" "-L" "<sysroot>\\lib\\rustlib\\x86_64-pc-windows-gnu\\lib\\self-contained" "-o" "C:\\Users\\李宇\\Desktop\\Rust_t\\my_first_project\\target\\debug\\deps\\my_first_project-975b8e7345fd2fc0.exe" "-Wl,--gc-sections" "-no-pie" "-nodefaultlibs" "<sysroot>\\lib\\rustlib\\x86_64-pc-windows-gnu\\lib\\rsend.o"
  = note: some arguments are omitted. use `--verbose` to show all linker arguments        
  = note: ld: cannot find C:\Users\.rustup\toolchains\stable-x86_64-pc-windows-gnu\lib\rustlib\x86_64-pc-windows-gnu\lib\self-contained\crt2.o: No such file or directory␍     
          ld: cannot find C:\Users\.rustup\toolchains\stable-x86_64-pc-windows-gnu\lib\rustlib\x86_64-pc-windows-gnu\lib\rsbegin.o: No such file or directory␍
                                  .
                                  . 
                                  .
          ld: cannot find -lmingwex: No such file or directory␍
          ld: cannot find -luser32: No such file or directory␍
          ld: cannot find -lkernel32: No such file or directory␍
          ld: cannot find C:\Users\.rustup\toolchains\stable-x86_64-pc-windows-gnu\lib\rustlib\x86_64-pc-windows-gnu\lib\rsend.o: No such file or directory␍


error: could not ***pile `my_first_project` (bin "my_first_project") due to 1 previous error

这个错误的核心原因是：你的 Rust 工具链当前用的是 GNU 版本（x86_64-pc-windows-gnu），但系统里没装对应的 GNU 链接器和依赖文件，导致编译时找不到需要的库和目标文件。
之前咱们提到过，Windows 上 Rust 有两种工具链：msvc（依赖 Visual Studio 构建工具）和 gnu（依赖 MinGW-w64）。现在的问题是工具链和系统环境没对应上，最直接的解决办法是 切换回 msvc 工具链（之前让你装的 Visual Studio 构建工具就是为这个准备的），步骤如下：
第一步：切换 Rust 工具链到 msvc 版本

1. 打开新的终端（一定要新打开，确保环境变量生效）；
2. 输入下面的命令，查看当前已安装的工具链：

rustup toolchain list

会看到类似这样的输出，带 * 的是当前在用的工具链：

stable-x86_64-pc-windows-gnu (default)
stable-x86_64-pc-windows-msvc

3. 切换到 msvc 工具链（如果没装 msvc 工具链，会自动下载安装）：

rustup default stable-x86_64-pc-windows-msvc

4. 验证切换是否成功：

rustup show

看到 “active toolchain” 是 stable-x86_64-pc-windows-msvc 就对了。

第二步：清理之前的编译缓存（避免残留文件干扰）
之前用 GNU 工具链编译过，可能留下了不兼容的缓存文件，需要清理一下：

1. 进入你的项目文件夹（比如 my_first_project）；
2. 删除 target 文件夹（这是编译生成的文件，删了没关系，后续会重新生成）；

• 可以用命令删：rm -rf target（PowerShell 或 Git Bash 可用）；
• 也可以手动找到文件夹右键删除。
  

第三步：重新运行项目

在项目文件夹里再次执行：

cargo run

这次会用 msvc 工具链编译，依赖你之前装的 Visual Studio 构建工具里的 link.exe，只要之前的构建工具装对了，就能正常编译运行，输出 Hello, Rust!。

四、构建工具没装对或环境变量没生效

***piling my_first_project v0.1.0 (C:\Users\Desktop\Rust_t\my_first_project)
error: linker `link.exe` not found
  |
  = note: program not found

note: the msvc targets depend on the msvc linker but `link.exe` was not found      

note: please ensure that Visual Studio 2017 or later, or Build Tools for Visual Studio were installed with the Visual C++ option.

note: VS Code is a different product, and is not sufficient.

error: could not ***pile `my_first_project` (bin "my_first_project") due to 1 previous error

这个错误说明虽然你切换到了 msvc 工具链，但系统里还是找不到 link.exe—— 这通常是因为 Visual Studio 构建工具没装对 或者 环境变量没生效。别着急，按下面的步骤一步步排查，肯定能解决：

第一步：确认 Visual Studio 构建工具的 “关键组件” 是否安装
之前让你装 “使用 C++ 的桌面开发” 时，可能漏选了核心组件。重新检查安装：

1. 打开开始菜单，找到并运行 “Visual Studio Installer”（安装工具的启动程序，不是 Visual Studio 本身）；
2. 在弹出的窗口中，找到你安装的 “Visual Studio 生成工具 2022”，点击 “修改”；
3. 在左侧勾选 “使用 C++ 的桌面开发” 后，一定要检查右侧的 “可选组件”：

• 必须勾选 “MSVC v143 - VS 2022 C++ x64/x86 生成工具”（版本号可能是 v144 等，选最新的就行）；
• 必须勾选 “Windows 10 SDK” 或 “Windows 11 SDK”（选一个就行，建议选和你系统版本一致的）；

4. 点击右下角 “修改”，等待安装完成（可能需要一段时间）。

第二步：手动验证 link.exe 是否存在
安装完成后，先确认 link.exe 到底有没有安装到电脑上：
5. 打开文件资源管理器，进入这个路径（按你的系统版本选一个）：

• 64 位系统通常在：C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.38.33130\bin\Hostx64\x64\
• （路径里的 14.38.33130 是版本号，可能不同，找类似的文件夹就行）

6. 看看这个文件夹里有没有 link.exe：

• 如果有，说明安装成功，只是系统没找到它；
• 如果没有，回到第一步，重新安装并确保勾选了正确的组件。

第三步：让系统找到 link.exe（配置环境变量）
如果 link.exe 存在但系统找不到，是因为它的路径没加入 “环境变量”。手动添加：
7. 按下 Win + R，输入 sysdm.cpl，回车打开 “系统属性”；
8. 点击 “高级”→“环境变量”；
9. 在 “系统变量” 里找到 Path，双击打开；
10. 点击 “新建”，把 link.exe 所在的文件夹路径填进去（比如上面找到的 C:\Program Files (x86)\Microsoft Visual Studio\2024\BuildTools\VC\Tools\MSVC\14.38.33130\bin\Hostx64\x64\）；
11. 一路点击 “确定” 保存，一定要重启电脑 让环境变量生效。

第四步：重启后再次尝试编译
重启电脑后，打开新的终端，进入项目文件夹，运行：

cargo run

这次系统应该能找到 link.exe 了，编译会顺利完成，最终输出 Hello, world!。

关键提醒：别漏了 “重启”

环境变量修改后必须重启电脑才能生效，很多人卡在这里。如果嫌重启麻烦，也可以重启终端并手动刷新环境变量（但新手容易操作错，还是重启最稳妥）。