你装好了 rust-analyzer，代码补全、跳转和重构都正常工作。然后你写了第一个 bug，按下 F5。
VS Code 弹出一个陌生的界面：launch.json 未找到，或者「No debugger found」。
然后你去搜教程，看到 CodeLLDB、MS C++ tools、rust-lldb、lldb.consoleMode、sourceFileMap……半小时后你放弃了调试，回到临时加 println! 日志的办法。
Rust 调试劝退的根源不是调试本身难，而是它由三个独立部件拼成：编译器工具链、调试器后端、编辑器适配层。任何一环没对上，F5 就是死的。 这篇文章用一次完整的真实调试会话，把这三环一次讲清。
一、第一环：选对调试器后端
Rust 不直接产出调试器，它产出的调试符号（DWARF / PDB）要交给 LLDB 或 GDB 解释。你的选择取决于平台：
Windows + MSVC 工具链（rustup 默认）：rustup 不提供适用的 rust-lldb 组件
这是最经典的坑。rustup component add rust-lldb 装完后，你会得到：
error: the 'rust-lldb.exe' binary, normally provided by the 'rustc' component,
is not applicable to the 'stable-x86_64-pc-windows-msvc' toolchain
这里的关键不是“Windows 上绝对没有 LLDB”，而是 rustup 不会为 stable-x86_64-pc-windows-msvc 提供可直接安装的 rust-lldb 组件。MSVC 产出的调试信息主要是 PDB，调试器还需要对应的 PDB 读取能力。所以 MSVC 用户的第一反应“装个 rust-lldb 就行”通常走不通。
推荐：CodeLLDB 扩展（vadimcn.vscode-lldb）
VS Code 扩展市场搜 CodeLLDB 安装。它自带一整套 LLDB（不需要你系统里装任何东西）；在本文的 Windows + MSVC 实测环境中，它能够读取 PDB 调试符号。这使它成为 Windows Rust 调试的优先尝试方案，但具体能力仍取决于扩展版本和本地调试器构建。
code --install-extension vadimcn.vscode-lldb
备选：MS C++ tools（ms-vscode.cpptools）
Visual Studio 的调试器移植版，也能读 PDB，但它是为 C++ 设计的：对 Rust 的类型视图、宏展开支持都很弱，配置也更啰嗦。除非你同时调试 C++ 代码，否则不推荐。
Linux / macOS：rust-lldb 或 CodeLLDB 都可以作为起点，但仍要确认当前工具链、调试器版本和符号格式匹配。
选型一句话：Windows 上调试 Rust，CodeLLDB 是默认答案；其他平台 rust-lldb 够用。
二、第二环：launch.json 从零配置
调试器装好了，F5 会提示你「创建 launch.json」。选 CodeLLDB 模板，然后把它改成这样：
{
"version": "0.2.0",
"configurations": [
{
"type": "lldb",
"request": "launch",
"name": "Debug (Rust)",
"program": "${workspaceFolder}/target/debug/debug-demo.exe",
"args": [],
"cwd": "${workspaceFolder}",
"stopOnEntry": false,
"terminal": "console"
}
]
}
逐字段解释——这是文章最值钱的部分：
| 字段 | 含义 | 常见错误 |
|---|---|---|
type | lldb = CodeLLDB；cppvsdbg = MS C++ tools | 填错直接「无法启动调试」 |
request | launch 启动新进程；attach 挂到运行中的进程 | 调试服务类程序用 attach |
program | 要调试的 exe 路径 | 最常见的坑：指向 src/main.rs 而不是编译产物 |
args | 传给程序的命令行参数 | 调试带参程序（如 CLI 工具）通常需要填写 |
cwd | 程序的工作目录 | 程序读相对路径文件时不对，表现为「文件找不到」 |
stopOnEntry | 启动即暂停在入口 | 调试 main 之前的初始化逻辑时有用 |
terminal | 程序 stdout 输出到哪里 | console 集成终端 / external 外部终端 |
上面的 program 使用 .exe，是 Windows 示例。Linux/macOS 通常没有扩展名；如果 Cargo binary 名称包含连字符，Windows 产物通常会把它转换为下划线，最终以 target/debug/ 中实际生成的文件名为准。
最关键的一条认知：program 指向的是编译产物，不是源码。 所以调试前必须编译过一次：
cargo build # debug 构建，含完整调试符号
如果 F5 后提示「文件不存在」，九成是没 build，或者 build 出的文件名和配置不一致（二进制名 = Cargo.toml 里的 name，下划线替换连字符）。
三、第三环：真实调试会话（实测记录）
我用一个 47 行的示例程序（订单打折 + 批量汇总）跑了完整会话。程序结构：
下面的输出来自本地 debug-demo 会话，代码和工具版本记录在文末；它是一次可复核的实验记录，不是 CodeLLDB 对所有项目都必然显示的固定格式。
let mut orders: Vec<Order> = Vec::new();
for i in 0..10 {
let mut order = Order::new(i);
order.add_item("rust book", 45.0);
order.add_item("coffee", 8.5);
apply_discount(&mut order, 10.0); // 断点 A：i == 5 时命中
orders.push(order);
}
let total = compute_batch_total(&orders);
println!("batch total: {:.2}", total); // 断点 B：观察 total
条件断点： 在断点 A 上右键 → Edit Breakpoint → 输入 i == 5。运行后程序准确停在第六次循环：
-> 42 apply_discount(&mut order, 10.0);
(lldb) frame variable
(unsigned int) i = 5
(debug_demo::Order) order = {
items = { len = 2 }
total = 53.5
id = 5
}
orders.len = 5（前 5 单已入列）、order.total = 53.5（45 + 8.5，还没打折）。条件断点是排查「第 N 次循环出错」类 bug 的利器——不用手点 10 次继续。
变量观察与调用栈： 变量面板直接展开 Order 结构体的字段；bt 显示完整调用链 main → call_once → __rust_begin_short_backtrace。
断点 B（println 前）： total = 481.49999999999989。数学上应该是 481.5，浮点二进制表示让它在调试器里露了原形——这不是 bug，是浮点数的日常。调试器能让你看到编译器与数学之间的那 0.00000000000011 的缝隙，这正是它比 println 强的地方。
四、常见坑清单（按踩坑频率排序）
1. 断点不命中：先查优化、profile 和二进制是否匹配
cargo build --release 编译的代码会被内联、重排，断点要么不命中要么停错行。调试永远用 cargo build（debug profile）。检查右下角状态栏确认没有 --release。
2. 变量显示残缺：当前 LLDB 后端可能没有完整 Rust 语言支持
当后端输出下面的警告时，变量展示能力会受限：
warning: This version of LLDB has no plugin for the language "rust".
Inspection of frame variables will be limited.
具体表现可能是：Option/Result/enum 显示成原始字段布局（__0、None 之类的内存视图），String 有时只显示 buf 而不显示文本。这是当前 LLDB 后端对 Rust 支持的限制，不一定影响断点和数值变量观察；看到 __0 时，先把它当作枚举底层布局，不要立刻判断配置失败。
3. 宏展开的代码：断点位置偏移
println!、vec! 展开出的代码在「你看到的行」和「实际代码」之间没有一一对应。在宏调用行下断点，有时会停在展开后的内部行。在宏调用之后的第一条普通语句上下断点，命中率最高。
4. 程序找不到文件/配置：cwd 与 args
程序读 ./data.txt 报错，先看 cwd 是不是程序期望的目录。CLI 工具（clap 系）调试时把参数写进 args，别在终端里手动跑。
5. attach 场景：request: attach + pid
调试长时间运行的服务（如 tokio 服务器），用 attach 模式，pid 填进程号（或用 ${command:pickProcess} 选择）。
五、总结：三环匹配表
| 环节 | 选择 | 一句话 |
|---|---|---|
| 工具链 | Windows 用 MSVC（默认） | 产出 PDB 符号 |
| 调试器 | CodeLLDB（Windows 推荐）/ rust-lldb（其他平台） | 能读 PDB 是关键 |
| 配置 | program 指向 debug 产物 | 忘了 build 一切白搭 |
| 日常习惯 | cargo build + 条件断点 | release 断点会「隐身」 |
三条原则：
- 调试器是选出来的，不是装出来的。 先确认工具链和调试器的匹配关系（MSVC ↔ PDB ↔ LLDB 插件），再谈配置。
- launch.json 的核心只有三个字段：program、args、cwd。 其他都是锦上添花。先把这三个填对，F5 就活了。
- 条件断点值得为它学一次。 排查循环/批量处理的 bug，它省下的时间远超配置它花的时间。
Rust 调试最贵的成本是「第一次配置失败后放弃」。把这 20 分钟花完，你换回来的是每次 F5 都能停在你想要的那一行。
如果仍然无法启动，按这个顺序记录信息：工具链目标三元组、CodeLLDB 版本、program 的实际路径、完整错误文本，以及 cargo build 是否成功。这样可以先判断问题发生在编译、符号读取还是 launch 配置，而不是反复修改 JSON。
FAQ
Q：Windows 上的 MSVC 工具链能直接使用 rust-lldb 吗？
A：通常不能。rustup 提供的 rust-lldb 不适用于 stable-x86_64-pc-windows-msvc；Windows MSVC 用户应优先安装 CodeLLDB。
Q：program 为什么不能填 src/main.rs？
A：调试器需要启动带调试符号的可执行文件。先运行 cargo build，再把 program 指向 target/debug/ 下实际生成的二进制文件。
Q：断点不命中时应该先查什么？
A：先确认使用的是 debug 构建而不是 --release，再确认 program 路径、cwd 和当前源码与二进制是否匹配。宏调用行还可能存在源码行映射偏移。
Q：CodeLLDB 显示 Option 或 Result 的内部字段，是配置错了吗？
A：不一定。某些 LLDB 版本缺少完整的 Rust 语言插件，复杂枚举可能显示为底层布局；这通常不影响断点、调用栈和数值变量观察。
延伸阅读
参考资料
- CodeLLDB 官方文档: https://github.com/vadimcn/vscode-lldb
- rust-analyzer 调试说明: https://rust-analyzer.github.io/book/vs_code.html
- 实测环境：VS Code 1.121 + rust-analyzer v0.3.2997 + CodeLLDB v1.12.2，Windows + stable-x86_64-pc-windows-msvc，Rust 1.95.0