★ FEATURED ARTICLE 简介面向需要在 Visual Studio Code 中借助 GDB 调试 Apollo 自动驾驶框架的 C 开发者尤其适合已经完成源码获取、依赖安装与 Bazel 构建却对断点会话配置、可执行文件路径填写和调试流程不够熟悉的中级读者。包内共 5 个文件以 4 个 JSON 配置文件和 1 个 HTML 说明页为主压缩后约 5KB其中配置文件可用于搭建启动、任务、编辑器与 C/C 属性等调试环境说明页则承载 Apollo 代码调试方法的图文梳理便于按模块查阅和对照。已有 1143 人学习说明该主题在 Apollo 开发群体中具备一定关注度。读者可参考现成配置理解程序路径、预启动任务、调试器类型等字段的作用并结合断点设置、单步执行、变量与调用栈观察、条件断点及日志参数调整形成从环境准备到问题定位的完整调试思路减少反复试错成本也能为后续排查复杂模块问题积累可复用的方法。1. 一个断点打不上的下午为什么 Apollo 的调试要在编译期就埋伏笔某开发者接手一个 Apollo 的感知模块容器里跑起来没报错输出就是不对。他在代码里撒了十几条打印语句每次改完都要重新build一遍、重新起一遍 dag一轮下来七八分钟一天就过去了一半。后来他把 VSCode 的断点挂上去图标是空心的灰圈鼠标悬停一行小字未绑定断点。折腾到晚上才发现问题根本不在 launch.json而在于他编译出来的二进制里压根没有调试符号。这套环境之所以难搞是因为它横跨三层宿主机上的 VSCode、容器里的编译产物、还有运行在容器网络里的进程。任何一层错位断点都会变成摆设。适合谁看正在用 Apollo 做模块开发、想从 printf 升级到 gdb 单步的人也适合把vscode gdb调试 apollo这条链路整体摸一遍、以后换模块不用重复踩坑的人。2. 环境准备容器、工具链与编译选项的三方对齐Apollo 的调试不是一个软件的事是三个东西必须对上号容器里的 gdb 能附加进程、二进制里带着符号表、VSCode 知道源码在哪。这三件事任何一件没做后面配 launch.json 都是白费劲。所以这一章不急着写配置先把地基打平。2.1 宿主机与容器内各装什么先明确一件事真正干活的是容器里的 gdbVSCode 只是个前端。所以宿主机的 VS Code 装什么、容器里有什么要分开列。下面这张表是我一般在动手前先核对的清单缺什么补什么。位置组件作用是否需要额外装宿主机VS Code编辑器与调试前端需要宿主机C/C 扩展提供 cppdbg 调试器类型、断点 UI需要宿主机Dev Containers 扩展把 VS Code 挂进容器源码路径与容器一致推荐容器内gdb≥ 8.x实际的调试后端Apollo 镜像已自带先gdb --version确认容器内gcc / clang 工具链编译时产出调试符号镜像已自带不用另装容器内构建脚本决定编译优化等级与-g镜像内自带有一点需要强调不要在宿主机上装一套 gdb然后又指望它去调容器里的进程。进程在容器的命名空间里宿主机的 gdb 看不到即便看到也是路径全错。所有调试动作都发生在容器内这是后面所有配置的前提。确认容器内环境的方法很简单进容器后执行# 确认 gdb 存在且支持 Python 脚本cpptools 的 pretty-printing 依赖它 gdb --version gdb -batch -ex python print(gdb-python-ok) # 确认构建脚本存在 ls -l apollo.sh第一段输出里如果带--with-python说明 gdb 内置 Python后面-enable-pretty-printing才能生效STL 容器才会显示成有意义的内容而不是一串地址。第二行是用来验证 Python 解释器能正常启动的输出gdb-python-ok就说明没问题。第三行只是确认工作区根目录里确实有构建脚本很多人把.vscode建在了modules/下面结果任务执行时 cwd 不对编译直接失败。2.2 用 VSCode Remote 接管 Apollo 容器Apollo 的开发容器一般是用仓库里的脚本起起来的先./docker/scripts/dev_start.sh拉起容器再./docker/scripts/dev_into.sh进去。既然容器已经在跑最省事的做法不是用 Dev Containers 重新构建而是让 VS Code 附加到这个正在运行的容器上。操作路径是命令面板 →Dev Containers: Attach to Running Container→ 选中那个 Apollo 容器。连上之后VS Code 会在容器里安装一个 server 端窗口左下角显示容器名此时打开的终端默认就在容器内。这一步做完编辑器里看到的源码路径、gdb 加载的路径、进程运行的路径三者才是同一套。接着把工作区指向 Apollo 根目录在根目录下建.vscode文件夹。为什么不放在子目录因为launch.json里的cwd、program、sourceFileMap都是相对工作区根目录算的放在子目录里会导致相对路径多一层调试器找不到可执行文件。这是最常见的路径配置错误之一。有一个细节容易被忽略用 Attach 方式连上容器时VS Code 打开的源码目录是容器内的视图和宿主机上的副本不是同一份。如果你在宿主机上改代码、容器里编译两边不同步断点行号就会错位。我一般会直接在容器视图里改或者确认挂载卷已经映射好宿主目录避免出现“改了没生效”的玄学问题。2.3 编译期开调试符号build_dbg 与优化等级断点空心灰圈八成是这一步没做。Apollo 的构建脚本通常区分优化版本和调试版本默认的build往往带-O2甚至更高符号表被裁剪gdb 即使 attach 上也只知道函数名、拿不到行号和局部变量。所以调试前必须切到调试构建# 进入容器后在 Apollo 工作区根目录执行 ./apollo.sh build_dbg # 如果只需要调某个模块可以只编这个 target省时间 ./apollo.sh build_dbg modules/perception/your_module # 编译完成后验证符号是否真的存在 readelf -S bazel-bin/modules/perception/your_module/your_module | grep -i debug第一条命令走的是调试模式的构建流程关键差别在于它会向编译器传-g并把优化等级压到-O0或接近-O0。优化等级这件事值得多说一句即使带了-g如果还是-O2编译器会把变量优化掉、把循环展开、把函数内联结果就是你明明在断点处停下了局部变量窗口却显示optimized out单步执行也会在源代码里乱跳看起来像“断点偏移”。所以调试构建必须是低优化级别两者缺一不可。第二条是增量编译单个 target。Apollo 的全量构建时间不短只改一个模块时没必要全编。需要注意 target 路径要写对写错了构建脚本会报找不到目标而不是报编译错误容易误判。第三条readelf -S是验证手段输出里能看到.debug_info、.debug_line、.debug_str这些节说明符号表确实被塞进二进制了。如果只看到.symtab而没有.debug_*那就是编译选项没生效回头检查构建脚本走的是不是调试分支别急着去改 launch.json。提示每次改完代码重新编译后都要重新确认一次符号节。有些增量构建会复用旧的 object 文件导致你以为重编了、其实没带-g。真遇到这种情况清一次构建缓存再全量编比在那里猜半天快。3. launch.json 拆解cppdbg 与 gdbserver 两种接法怎么选配置文件写错一个字段调试器就起不来而且它的报错信息往往很含糊——只说“无法启动调试会话”不告诉你是program路径错了还是miDebuggerPath错了。所以这一章按“能直接跑起来”的顺序把每个字段的作用和容易填错的地方讲清楚。3.1 一份能直接跑的 launch.json先给一份我在 Apollo 模块调试里常用到的配置放在.vscode/launch.json改掉program和args两处就能用。{ version: 0.2.0, configurations: [ { name: Apollo: 启动并调试模块, type: cppdbg, request: launch, program: ${workspaceFolder}/bazel-bin/modules/perception/your_module/your_module, args: [ -dag_config_filemodules/perception/your_module/conf/dag.conf, -module_nameyour_module ], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [], externalConsole: false, MIMode: gdb, miDebuggerPath: /usr/bin/gdb, setupCommands: [ { description: 启用整齐打印STL 容器才显示为内容而不是地址, text: -enable-pretty-printing, ignoreFailures: true }, { description: 只调试子进程cyber 模块常以 fork 方式拉起, text: set follow-fork-mode child, ignoreFailures: true }, { description: 关掉启动时的确认提示避免会话卡在交互上, text: set confirm off, ignoreFailures: true } ], sourceFileMap: { /apollo: ${workspaceFolder} }, preLaunchTask: apollo: build_dbg } ] }逐字段说关键的几个。type固定为cppdbg这是 VS Code 的 C/C 扩展提供的调试器类型对应底层的 gdb MI 协议如果写成cppvsdbg那是 Windows 上的调试器在 Linux 容器里必然起不来。request用launch表示“由调试器负责启动程序”适合从入口开始调如果程序已经在跑要用attach那是 3.3 的内容。program指向编译产物Apollo 的产物在bazel-bin/下按 target 路径排布。这里最容易错的是写成源码路径或者相对路径少了前缀。判断方法在容器终端里ls一下这个路径能ls到就说明写对了。cwd填工作区根目录而不是program所在目录因为 Apollo 的很多模块用相对路径加载配置和插件cwd错了会报“找不到配置文件”看起来像调试器的问题其实是工作目录的问题。sourceFileMap是 Apollo 场景里最关键的一条。容器里的构建产物编译时的源码绝对路径可能是/apollo/modules/...这种形式而 VS Code 打开的工作区路径未必完全一致。一旦对不上gdb 报的断点位置就是“另一个文件”断点自然绑不上。这条映射的意思是“把调试信息里记录的/apollo前缀换成当前工作区路径”。我的习惯是先在容器里用readelf --debug-dumpinfo看一眼编译单元记录的目录再照着填映射比猜快得多。setupCommands里的-enable-pretty-printing解决的是变量显示问题不开它一个std::vector在变量面板里就是{...}或者一坨地址开了之后能展开成实际元素。follow-fork-mode child后面 4.3 会展开讲这里先放着Apollo 的 cyber 模块经常有 fork 行为不设这个断点会打在父进程上然后什么都不发生。preLaunchTask是让调试前自动跑一次编译避免“改了代码没重编、断点打在旧行号”这种坑。对应的任务写在tasks.json里。3.2 tasks.json 与 preLaunchTask 的配合preLaunchTask填的是一个任务名这个任务必须有同名定义否则 VS Code 会弹“找不到 preLaunchTask”然后拒绝启动调试。最小可用的任务定义如下{ version: 2.0.0, tasks: [ { label: apollo: build_dbg, type: shell, command: ./apollo.sh build_dbg modules/perception/your_module, options: { cwd: ${workspaceFolder} }, group: { kind: build, isDefault: true }, problemMatcher: [$gcc] } ] }label必须和launch.json里的preLaunchTask字符串完全一致大小写和空格都算。command里我把模块 target 写死了这样每次调试前只增量编这一个模块几秒到几十秒如果写全量build_dbg一次调试要等好几分钟体验会崩。options.cwd设成工作区根目录原因同上构建脚本对执行目录敏感。problemMatcher用$gcc编译报错会直接以可点击的形式出现在“问题”面板里点一下跳到出错行。不加这个编译失败只会在终端里刷一屏日志调试器那边只会提示“preLaunchTask 失败”你还得自己翻回去找。一个实际取舍如果你调试的是已经稳定、很少改动的模块可以把preLaunchTask去掉改成手动编译。原因是自动编译有时会打断你的思路——你只是想看看某个变量的值结果它先把整个模块重编了一遍。我一般是开发前期开着自动编译后期定位疑难问题时关掉手动控制节奏。3.3 attach 到已运行进程不重启也能调很多 Apollo 的问题只在运行一段时间后才复现比如消息队列积压、某个回调在特定时序下才出错。这时候重启进程重新launch会丢现场得用attach。有两种接法。第一种是直接附加到容器内已有的进程{ name: Apollo: attach 到运行中的进程, type: cppdbg, request: attach, program: ${workspaceFolder}/bazel-bin/modules/perception/your_module/your_module, processId: ${command:pickProcess}, MIMode: gdb, miDebuggerPath: /usr/bin/gdb, setupCommands: [ { text: -enable-pretty-printing, ignoreFailures: true } ], sourceFileMap: { /apollo: ${workspaceFolder} } }processId用${command:pickProcess}启动调试时会弹出一个进程列表让你选。这里有个前提列表里能看到的进程取决于 VS Code server 所在命名空间能看到的范围所以必须在容器内的 VS Code 窗口里操作从宿主机窗口点会看不到目标。program在 attach 模式下不是“要启动的程序”而是“用来对齐符号的可执行文件”。这一条填错的后果很典型attach 成功了调用栈里全是??断点也绑不上。原因就是进程实际加载的二进制和你给出的这个文件的符号信息对不上——可能是路径不同也可能是你重编过、而正在运行的还是旧版本。第二种是 gdbserver 方式适合进程起不来或者不方便让 gdb 直接接管的情况# 在容器内用 gdbserver 把目标程序挂起来监听 1234 端口 gdbserver :1234 ./bazel-bin/modules/perception/your_module/your_module \ -dag_config_filemodules/perception/your_module/conf/dag.conf然后launch.json里不写program的启动逻辑改用远程地址{ name: Apollo: gdbserver 远程调试, type: cppdbg, request: launch, program: ${workspaceFolder}/bazel-bin/modules/perception/your_module/your_module, miDebuggerServerAddress: 127.0.0.1:1234, MIMode: gdb, miDebuggerPath: /usr/bin/gdb, sourceFileMap: { /apollo: ${workspaceFolder} } }miDebuggerServerAddress指向 gdbserver 监听的地址。端口选 1234 只是习惯换成别的也行但两边要一致。这种方式的好处是目标程序的生命周期和调试器解耦VS Code 崩了、重连进程还在不用重新复现。缺点是多一层转发启动稍慢而且gdbserver本身对多线程的支持不如原生 gdb 顺滑调试复杂并发问题时我一般不选它。4. 断点实操从 main 一路打进 cyber 模块配置能起来只是第一步真正花时间的是“断点到底该打在哪”。Apollo 的模块大多不是简单的main一路到底而是由框架拉起、回调驱动很多人第一次调的时候会发现主函数跑完了、自己关心的逻辑一行没停。这一章讲的就是怎么把断点放到正确的位置。4.1 三种启动调试的姿势与适用场景第一种从入口开始单步。stopAtEntry设为true调试器会在main的第一行停下适合研究模块初始化流程、看配置是怎么解析的。缺点是 Apollo 的初始化链路很长从main走到业务回调可能要按几十次单步效率低。第二种先跑起来再打断点。stopAtEntry设为false程序正常启动你在编辑器里提前打好断点等它命中。这是日常最常用的方式。要注意的是断点必须在程序执行到那一行之前就存在如果是启动瞬间就执行的代码等你手动加断点时已经错过了。这种位置的断点要提前放好。第三种attach 之后补断点。适合线上复现类问题进程已经跑了几小时你 attach 上去然后在可疑分支上打断点。这种方式有个前提program里的符号必须和运行中的二进制严格一致否则断点绑定失败。我一般会在 attach 前先md5sum一下运行中的可执行文件和本地文件对不上就不折腾了直接重编重跑。三种方式都指向同一个事实断点能不能绑定取决于调试器有没有那个地址对应的行号信息跟你点得快不快没关系。所以遇到绑不上的断点第一反应应该是去查符号而不是反复重启。4.2 条件断点与日志点别让断点停成筛子Apollo 的模块动辄每几十毫秒跑一次回调断点一打程序就再也走不动了——每按一次继续下一帧立刻又停下来。这时候要么用条件断点要么用日志点。条件断点的做法是在断点右键 → 编辑断点 → 输入表达式比如frame_count 1000 obstacle.id 42表达式为真时才停下其余时候直接放行。写条件断点有两个注意事项一是表达式里不要放有副作用的调用gdb 求值时会真的执行它可能改变程序状态二是条件断点的求值本身有开销如果表达式里访问了复杂对象程序会明显变慢这时候不如改用日志点。日志点的做法是右键 → 添加日志点输入一段文本比如hit frame{frame_count}, size{obstacles.size()}花括号里可以放表达式命中时不中断只在调试控制台打印。这个功能在排查“某段逻辑到底有没有被执行”时特别好用比在代码里加printf再重编快得多。我第一次用它之后就基本不再往代码里插打印语句了尤其是那种需要跑一段时间才复现的问题。有一点要提醒日志点的表达式求值同样走 gdb打印复杂容器时如果不启用 pretty-printing你会看到一堆内存地址得先确认 3.1 里那条-enable-pretty-printing生效了。4.3 多进程与多线程follow-fork 和调度锁定Apollo 的模块经常不是单进程框架可能会 fork 子进程去跑任务或者起多个线程处理不同的消息通道。默认情况下 gdb 只跟随父进程子进程一 fork 出去就不归你管了断点打在里面也不会停。解决办法是在setupCommands里指定跟随策略set follow-fork-mode child设成child表示 fork 后跟子进程走父进程继续跑。反过来还有一个set detach-on-fork off意思是 fork 后两个进程都留在 gdb 管理下可以来回切换。后者更强大但也更容易乱我一般只在明确需要同时观察父子时开日常排查用child就够了。多线程场景的麻烦在于断点命中时哪个线程停下来。gdb 默认是“当前线程停、其他继续”但实际表现常常是你在一个无关线程上停住了调用栈和你关心的业务逻辑毫不相干。可以在断点上设置只在特定线程生效或者用调度锁定set scheduler-locking step这个设置只在单步时锁定当前线程其他线程不跑避免你单步走两步就被别的线程打断。用on会锁得更死所有线程都停容易导致依赖定时器的逻辑卡住一般不推荐。还有一个实操技巧在“调用堆栈”面板里切线程比在 gdb 命令行里thread apply all bt看得清楚。命中一个可疑断点后先把所有线程的栈扫一遍看看有没有别的线程正卡在锁或者条件变量上很多“逻辑没问题但结果不对”的情况答案就在另一个线程的栈里。5. 避坑与排查断点灰掉、符号丢失、attach 卡死的五种现场下面这五条都是我在实际环境里撞过的按“现象 → 原因 → 解决”的顺序记遇到同类问题可以直接对号。5.1 断点绑定失败与符号相关的两类现场现象一断点是空心灰圈悬停提示“未绑定断点”。原因是调试器在当前加载的符号里找不到这一行对应的地址。可能是编译时没带-g可能是sourceFileMap映射错导致它去看了另一个文件也可能是程序还没加载到那个模块——动态库形式的模块要等dlopen之后才有符号。解决按顺序来先在容器里readelf -S binary | grep debug确认符号存在再检查sourceFileMap是否把编译期记录的绝对路径正确映射到了工作区最后确认断点所在的代码是不是在动态库里如果是把它设在库加载之后的位置或者在调试控制台手动break一次。三步下来基本能定位到底是哪一环断的。现象二attach 成功但调用栈全显示??变量面板空白。原因是program指向的可执行文件和进程实际加载的那份不一致。常见于你重编了代码但旧进程还在跑或者容器里存在多个构建产物副本。解决办法是先确认进程实际的可执行文件路径容器内看/proc/pid/exe指向哪里然后让program指向同一份文件。如果确实是版本不一致重新编译再重启进程不要指望用一份新符号去调一个旧二进制那只会得到错误的行号比调不出来更危险。5.2 启动卡死与重编后错位现象三点下调试后一直停在“正在启动调试器”没有任何输出。原因是 gdb 起不来或者起来了但无权附加到目标进程。容器里常见的限制是 ptrace 被禁表现为 gdb 报ptrace: Operation not permitted但这条错误有时被前端吞掉只剩一个卡住的界面。解决在容器终端里手动跑一次gdb --args binary args能不能正常进入(gdb)提示符。如果手动也报 ptrace 错误说明容器启动参数缺了相应权限需要重启容器时放开这一项。手动能进、只是 VS Code 里卡住那就是端口或 server 端的问题重连一次容器窗口通常能恢复。现象四改了代码断点位置跟着漂了一行或者停在了注释上。原因是运行的二进制还是旧的或者只重新编译了部分 target导致目标文件之间的行号信息不一致。这个现象迷惑性很强因为断点确实停下了只是停错地方。解决办法是确认preLaunchTask真的执行成功了看构建输出里有没有“up-to-date”这类跳过编译的提示。只要对符号有疑问就清一次构建缓存做全量调试构建慢是慢一点但比在错误行号上分析半天强。这条我吃过亏从那以后凡是断点位置看起来不对第一件事就是清缓存重编。现象五断点命中后单步执行顺序和源码对不上变量突然变成optimized out。原因是二进制带了符号但没关优化-O2下的内联和重排会让源码行和执行流不再一一对应。这种不是配置错误是构建配置选错了模式。解决办法是切到调试构建重编确认优化等级降下来了。顺便看一眼构建脚本走的哪条分支有些时候是参数拼写不一致导致走了默认分支看起来像“构建成功”实际编的还是优化版本。注意这五条里只有第三条属于环境权限问题其余四条全部指向“符号和源码是否对得上”。养成先验证符号、再改配置的习惯能省掉一大半无效折腾。6. 验证跑通三分钟确认调试链路真的通了配置写完之后最怕的是“看起来能跑”。断点停了但停的位置对不对变量显示正常但那是真的值还是缓存的旧值我一般用下面这套流程做最终确认三步走完链路才算真的通。第一步验证符号与源码的对齐关系。不要靠肉眼比对行号用调试器自己给出的信息# 在容器内执行看调试信息里记录源码目录是什么 readelf --debug-dumpinfo bazel-bin/modules/perception/your_module/your_module \ | grep -m 5 DW_AT_comp_dir # 再确认这些源码文件在工作区里确实存在同名同路径 ls modules/perception/your_module/第一条输出的是编译时记录的目录前缀第二条确认源码实际位置。两者如果不一致就回到 3.1 去调sourceFileMap而不是反复重启调试会话。这一步做完断点绑定问题基本就绝迹了。第二步用一个“必然命中、值可预测”的位置做冒烟测试。我会在模块初始化函数的头几行放一个临时断点启动调试观察三件事观察点正常表现异常含义断点图标实心红点空心灰圈表示未绑定调用堆栈能显示完整函数名与行号显示??表示符号不匹配局部变量结构体可展开、有字段值显示optimized out表示优化未关三项都正常说明“编译带符号 路径映射正确 调试器已接管”这条链路是通的。任何一项异常对应的排查路径就是第 5 章里的那几条不用重新从头配。第三步验证条件断点和日志点在真实负载下的表现。把断点改成带条件的让程序跑满一分钟看它是否只在条件成立时停下再把断点换成日志点看调试控制台是否按预期刷出内容而不中断执行。这一步是为了确认pretty-printing生效、表达式求值不报错——因为条件表达式里一旦引用了一个作用域外或者被优化掉的变量gdb 会静默求值失败断点看起来“永不命中”很容易被误判成没绑上。最后补一个我自己的习惯每次换模块或者重新拉容器我都会先跑一遍第一步的readelf验证不跳过。因为容器重建之后构建产物和挂载路径都可能变而launch.json里的映射是写死的不变的东西只有源码。这个动作花不到一分钟但能挡掉后面一小时的“断点为什么不生效”。希望这套流程能帮到你下次再遇到灰圈断点先查符号别急着怀疑编辑器。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
