企业官网建设流程全解析

简介：Visual Studio Code 配合 GDB 调试 Apollo 自动驾驶项目的断点调试方法，适合刚接触 Apollo 或希望摆脱纯命令行调试的 C++ 开发者。压缩包共 5 个文件，主体为 4 个 JSON 配置和 1 个 HTML 说明；JSON 分别覆盖 launch.json、tasks.json、settings.json、c_cpp_properties.json 等调试与编译关键项，HTML 则讲解从安装 C/C++ 扩展、配置环境到设置断点、F5 启动调试、观察变量和调用栈的完整流程。内容虽少但切入点明确，已有 1141 人学习下载。读者可直接参考其中的配置模板，结合自己的 bazel-bin 可执行文件路径做替换，快速搭建可复用的 Apollo 调试环境；HTML 中的操作提示也有助于理解单步执行、条件断点、watch 窗口和调试日志参数等常见用法，减少在复杂工程中排查调试器连接问题的成本。

1. 在VSCode里断点调试Apollo：别用launch，直接attach到进程

在VSCode里用gdb调试Apollo代码，很多人第一反应是打开一个源码文件、按F5、等程序跑起来。Apollo不是普通单进程工程——它是基于Cyber框架的分布式多进程系统，模块之间靠共享内存和Channel通信，一个planning模块要正确跑起来，前面得有感知、定位、预测一整条链路的数据喂着。直接在launch模式下启动某个模块，环境上下文对不上，跑都跑不起来。反直觉的结论是：真正好用的办法是先把模块跑起来，再用VSCode的gdb attach到那个进程上，断点、变量、调用栈全部照常工作。这套路适合要改Apollo算法逻辑、需要打断点跟数据流的从业者，也适合刚接手Apollo源码、想弄清楚某个模块到底怎么跑的人。

2. 环境准备：从容器权限到bazel的调试符号

Apollo通常跑在Docker容器里，开发环境、Cyber运行时、编译产物全在容器内。VSCode的断点调试本身依赖的是一套能访问目标进程的GDB环境，所以环境准备这一步做的事情不是“打开VSCode”，而是先把容器、编译、符号这三件事对齐。我拆过几套Apollo环境，大多数调试失败不是断点没设对，而是前置条件没满足。

2.1 进入容器并确认ptrace权限

attach到进程在Linux上依赖ptrace系统调用，容器里缺了权限会直接报“Operation not permitted”。这个坑我见过太多次。先确认当前容器能不能attach：

docker start apollo_dev docker exec -it apollo_dev bash cat /proc/sys/kernel/yama/ptrace_scope

这一步的输出如果是1或2，说明宿主内核默认限制了ptrace。1表示只能attach到子进程，2表示只有root且带CAP_SYS_PTRACE才能attach。容器里的进程如果想被宿主机或容器内其他进程attach，需要容器有SYS_PTRACE能力。如果cat出来的值是1或2，最干净的做法是把这个容器删掉，用带--cap-add=SYS_PTRACE参数的方式重新启动。

这个检查为什么值得放在第一步：因为GDB attach失败的报错信息里虽然有“ptrace”字样，但人眼往往被那一长串路径信息带偏，以为是符号配置出了问题。先把权限确认掉，后面配置launch.json时才不会到处怀疑。

2.2 用bazel build编译带调试符号的模块

Apollo用Bazel构建，默认配置很多是优化过的release版本，没有-g调试符号，也没有关闭优化。直接拿默认产物去调试，断点要么打不上，要么命中了变量全是<optimized out>。所以调试前要单独编译目标模块：

source /apollo/cyber/setup.bash bazel build -c dbg //modules/planning/planning:planning

-c dbg在Bazel里是编译模式参数，等价于在gcc命令行里加-g -O0，它告诉Bazel用debug配置编译这个目标及其依赖。//modules/planning/planning:planning是目标路径，前面是BUILD文件所在目录，冒号后面是目标名。如果你要调试感知模块，把路径换成perception对应的目标即可，规则一样。

如果这个模块下已经有多个二进制目标，拿不准名字，可以先bazel query //modules/planning/...列出该目录下所有目标，再挑要调试的那个。注意-attach调试时，进程是已经跑起来的，编译出带符号的二进制只是第一步，实际加载到GDB里的符号来自运行中的进程，所以待会儿要让运行中的进程使用这份新编译的产物。

2.3 确认二进制和符号表真的对上了

编译完了，还要确认产物确实带调试信息，不然花了十分钟编译，启动VSCode后照样一脸闷。确认方法：

file bazel-bin/modules/planning/planning/planning readelf -S bazel-bin/modules/planning/planning/planning | grep debug

file能看出ELF类型和是否strip过，readelf -S如果看到.debug_info、.debug_line这些section，说明调试符号在里面。有些项目构建脚本最后会strip一遍，产物比预期小很多，看到这种要回头查构建配置。

还要核对构建ID和进程实际加载的二进制是否一致。GDB运行时依赖build-id匹配，如果二进制重新编译过但进程还在跑旧的，GDB会警告“no debugging symbols found”。所以每次改代码重编译后，最稳妥的做法是重启目标模块再重新attach，而不是让GDB硬加载一份对不上的符号表。这个流程我在4.3节还会细说。

3. 配置GDB attach：launch.json逐行拆解与参数边界

环境就绪后，核心工作落在VSCode的调试配置上。这里有两个选择：用launch模式还是attach模式。绝大多数第一次在VSCode里调试Apollo的人都会选launch，因为IDE默认引导你做这件事。它也是翻车重灾区。

3.1 为什么attach模式才是正解

Apollo模块的启动通常不只是一个二进制那么简单。planning模块往往由mainboard带配置启动，mainboard负责拉起Cyber框架、加载模块插件、初始化所有依赖。你要调试的算法代码有的是编译在mainboard里的，有的是单独编译成.so在运行时被dlopen加载的。

launch模式下，VSCode会接管进程的启动，这要求你提供完整的可执行文件路径、环境变量、启动参数。Apollo的mainboard启动参数里带一长串配置路径和依赖，漏一个、错一个，进程行为就变了。而attach模式是让VSCode里的GDB挂到一个已经在跑的进程上，进程的环境、配置、启动方式全部保持原样，你只关心代码执行流。这也是为什么实际调试Apollo时，attach比launch可靠得多。

3.2 一份可以抄的launch.json

在VSCode里打开Apollo源码目录，创建.vscode/launch.json，配置如下：

{ "version": "0.2.0", "configurations": [ { "name": "Apollo mainboard attach", "type": "cppdbg", "request": "attach", "program": "/apollo/bazel-bin/cyber/mainboard", "processId": "${command:pickProcess}", "MIMode": "gdb", "miDebuggerPath": "/usr/bin/gdb", "cwd": "/apollo", "setupCommands": [ { "text": "set solib-search-path /apollo/bazel-bin/modules/planning:/apollo/bazel-bin/cyber", "ignoreFailures": true }, { "text": "set breakpoint pending on", "ignoreFailures": true } ] } ] }

先解析program字段。它不是告诉你按F5会启动这个程序，而是告诉GDB“目标进程的可执行文件在哪个位置”。写错成模块自身的二进制路径，attach后GDB会提示找不到目标文件，即使进程选对了也会中断调试。所以这里统一指向/apollo/bazel-bin/cyber/mainboard。

processId用了${command:pickProcess}，运行调试时VSCode会弹一个进程列表给你选。注意这里列的是容器内进程，不是宿主机进程，前提是你用Remote-SSH连进了容器环境。选进程时看命令行，Apollo的mainboard进程一般带-p /apollo/modules/xxx/conf/xxx.pb.txt，那个就是要选的。

setupCommands是每次GDB启动时自动执行的命令列表。set solib-search-path指定共享库查找路径，Apollo模块的算法代码很多在.so里，GDB要从这个路径去找符号文件。路径用冒号分隔多个目录，不会递归查找子目录，所以要把涉及的模块一行行列全。set breakpoint pending on是关键中的关键：允许断点在共享库尚未加载时先挂起，等库被dlopen进来后自动命中。Apollo模块运行时才加载插件库，没有这一行，很多断点会直接变成“未解析”状态。

3.3 启动attach后的完整操作流程

配置保存后，先手动把目标模块启动起来（正常业务环境怎么启动就怎么启动），然后按F5进入attach流程。VSCode弹出进程列表，筛选mainboard，选中后调试器就绪。此时界面左侧的调试工具栏会出现，但注意：进程并不会停下来，它还在继续跑，因为attach模式下GDB默认不打断执行流，直到你设置了断点且该行代码被执行到。

接下来打开要调试的源文件，在目标行打上断点，然后通过触发业务逻辑（比如发送一个planning请求、播包回放）让代码跑到那一行。断点图标变实心、命中断点后，就能看到调用栈、局部变量、watch表达式了。

这里有个新手会迷路的点：attach后进程不停在main函数，而是停在下一条要执行的指令处，一般在某个系统调用或线程切换位置。这不是调试器坏了，是attach的默认语义。不用去管它当前停在哪，直接设好断点、点继续、等断点命中就行。

4. 断点为什么不命中：符号表加载与源码路径映射

attached进去了，进程也选对了，断点打上去却是空心圆，或者命中了但显示的代码行对不上。这是Apollo调试里出现频率最高的问题。符号表加载和源码路径映射这两个机制不搞清楚，断点就一直是“薛定谔的断点”。

4.1 先查GDB到底加载了哪些符号

断点是空心状态时，先别一头扎进launch.json乱改。打开VSCode的调试控制台，直接输入GDB命令：

info sharedlibrary

这个命令会列出当前进程已经加载的所有共享库及符号加载状态。重点看包含planning字样的那个.so有没有出现在列表里。如果列表里压根没有这个库，说明它还没被dlopen加载，pending断点会继续挂起等库加载。如果列表里有库但符号状态显示“Symbols not loaded”，说明solib-search-path没指到正确的位置。

出现后一种情况的典型原因是set solib-search-path写得太宽或太窄。太宽是指写了/apollo/bazel-bin，GDB只会在这个目录本身查找，而.so的实际位置在/apollo/bazel-bin/modules/planning/planning这种深层目录里，不递归等于没写。太窄是指只写了某一个小目录，另一个模块的库加载时找不到符号。我一般会把要调试的模块路径一个不落都列上去。

4.2 源码路径映射：让GDB找到编辑器里的文件

另一个常见问题：断点命中在某个地址上，但编辑器里没高亮，控制台提示“Cannot find source file xxx.cc”。原因是GDB生成的调试信息里记录的是编译时的绝对路径，这个路径在Bazel里往往是/apollo/bazel-out/k8-opt/bin/modules/planning/...这种虚拟路径，而源码实际在/apollo/modules/planning/...，两者不一致。

解决办法是在launch.json里加sourceFileMap字段做路径替换：

"sourceFileMap": { "/apollo/bazel-out/k8-opt/bin/virtual": "/apollo/modules" }

如果用的是同路径内调试，也就是容器内源码就在/apollo/modules，GDB报告的路径也在这个目录下，其实不需要任何映射。真正需要映射的是编译输出目录和源码目录不一致的情况。判断方法很简单：看调试控制台里GDB日志里Source file后的路径和实际源码路径对不对得上。Bazel的k8-opt路径出现频率最高，先把这条映射加上，多半能解决空心断点问题。

4.3 模块重启后符号失效的恢复流程

修改代码后重新编译，再把模块进程重启，这是Apollo开发的标准循环。但这里有个隐蔽的坑：二进制被覆盖后，旧进程还占着文件句柄，Bazel编译新版本会报文件占用错误。所以正确的顺序是先停进程，再编译，再启动。

pkill -f mainboard bazel build -c dbg //modules/planning/planning:planning # 重新启动模块

重启后进程有了新build-id，GDB如果还挂着旧符号，会有一堆“Load new symbol table from ...?”的提示，有可能自动重新加载，也有可能不加载。为了干净，我通常会把attach会话结束掉，重新走一遍F5，再选新进程。不要嫌麻烦，这一步省了后面推断变量值全是错的。

5. Apollo调试的常见坑：现象、原因、解决一条条说清

这部分是实操中被反复磨出来的记录。每一条都是我或身边同事在VSCode里调试Apollo时真实遇到过的，按现象、原因、解决三个层次说清楚。

5.1 F5后进程列表里找不到mainboard

现象是attach时进程列表里只有cyber_launch或者其他辅助进程，目标mainboard不在列表里，或者列表里进程太多分不清哪个是。

原因是VSCode的pickProcess在列进程时来自/proc扫描，如果目标进程权限不够或容器内/proc挂载不全，进程就不会出现。另一个情况是容器里同时跑了多个Apollo实例，多个mainboard并列，命令行看着都差不多，选错就出错。

解决方法是给launch.json的processId字段换成${command:pickProcess}时先用ps -ef | grep mainboard在终端确认目标进程的完整命令行。多个实例时靠配置文件名区分，比如planning_config.pb.txt对应的就是planning模块。如果列表里压根没有，检查attach时的用户权限，改成root用户运行VSCode的Remote-SSH会话。

5.2 attach时报“ptrace: Operation not permitted”

现象是F5后立刻弹出一个对话框，里面既有ptrace字样又有一大段路径信息。原因基本锁定在容器能力缺失或宿主机kernel.yama.ptrace_scope限制，不是GDB配置问题。

解决方法是回到2.1节，用带--cap-add=SYS_PTRACE的容器启动参数重建容器。如果容器不能重建，退而求其次在宿主机执行echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope临时放开限制，但注意容器和宿主机是共享这个内核参数的，这个操作会影响宿主机上所有进程的ptrace策略，适合临时调试使用。

5.3 断点是实心，但命中后变量全是<optimized out>

现象是断点能停，但左侧变量窗口里全是“optimized out”，单步调试也乱跳，仿佛代码执行顺序和源码对不上。

原因是进程实际加载的二进制不是-c dbg编译出来的那份，可能是之前用默认模式编译的release版本，或者Bazel缓存命中了一个优化版本。解决方法是检查进程启动路径和二进制路径是否一致，再确认bazel build -c dbg确实输出到了bazel-bin，而不是被缓存挡住了。最直接的手段：把目标二进制删掉重新编译，不信任Bazel的增量缓存。

5.4 attach后停在一个奇怪的位置，不是期望的调试入口

现象是attach成功后，编辑器显示停在一个反人类的系统库或是某个线程池里，很多新手以为调试失败了，直接关掉。

原因是attach的默认行为是当GDB挂上进程时，进程会暂停在“当前正在执行的指令”，这个位置大概率不在你的业务代码里。解决方法是别管它，先把要用的断点批量设好，然后点继续按钮，让进程跑起来，等代码执行到断点处自然会停下来。实在想让调试入口固定，就找一个一定会被调到的函数，比如planning的RunOnce，在那里设断点配合pending机制。

6. 进阶：用条件断点和.gdbinit把Apollo调试变成半自动

断点能命中只是第一步，Apollo的planning循环是几十赫兹在跑，一个断点打在高频路径上，每帧都能停一次，手点继续点到怀疑人生。条件断点和调试脚本能把这种重复劳动压下去，让断点只在真正关心的数据条件下触发。

6.1 条件断点过滤高频循环

在VSCode的调试控制台里可以直接输入GDB命令设置条件断点，相比在IDE里右键编辑断点，命令形式更适合批量操作：

break modules/planning/.../planner.cc:240 if strcmp(lane_id.c_str(), "lane_1") == 0

这条命令的意思是：在planner.cpp第240行设断点，只有当变量lane_id的字符串等于lane_1时停下来。strcmp是GDB表达式里比较std::string的常用方式，因为直接写lane_id == "lane_1"在GDB对C++类型解析时不稳定，strcmp返回0表示相等，这个条件写法几乎不会踩坑。

如果只想每N次命中一次，比如想知道进这个循环的次数，用ignore命令：

break modules/planning/.../planner.cc:240 ignore 1 10

ignore 1 10表示忽略断点1的前10次命中，从第11次开始停。这在调试循环内偶发bug时特别实用，既能确认循环执行次数，又不会让调试器每帧都弹出来。

6.2 把常用断点写进脚本，一次source全部恢复

Apollo模块每次重启都要重新attach、重新设断点，手动重复这套工作很消耗耐心。我的习惯是把常用断点写到一个.gdbinit脚本文件里，放在/apollo目录下：

# /apollo/apollo_break.gdb set breakpoint pending on break modules/planning/tasks/.../speed_decider.cc:180 break modules/planning/tasks/.../path_decider.cc:95 if scenario_type == 3

然后在launch.json的setupCommands里追加一行source，让每次attach自动加载这个脚本：

{ "text": "source /apollo/apollo_break.gdb", "ignoreFailures": true }

这样每次重启模块后重新attach，常用断点会自动恢复，不用再翻历史记录一个个找。脚本里还能顺手写set print pretty on这种常用输出格式，省得每次调试时反复调。

从那以后，我每次接Apollo调试任务，强制自己先走三件事：确认容器带ptrace权限、用-c dbg编译目标模块、检查断点脚本里的路径和当前源码路径对得上。这三步少做一步，都会在中途翻车，回头查半天还以为是GDB配置问题。这套流程跑了几个模拟项目之后，基本不再被断点打不上、变量被优化掉这类问题缠住。希望帮到你。

本文还有配套的精品资源，点击获取