企业官网建设流程全解析

简介：面向在VS Code中使用GDB断点调试Apollo自动驾驶项目的开发者，资源包内提供了一套可直接落地的调试配置文件与配套说明文档。包内共5个文件，以4个json配置为主——涵盖launch.json、tasks.json、settings.json与c_cpp_properties.json，分别用于定义调试启动参数、编译任务、编辑器环境与C/C++ IntelliSense设置，另附一份HTML格式的调试方法详解，从环境配置到断点管理逐项拆解Apollo项目的调试要点。整个压缩包仅5KB，轻量聚焦，已有1141人学习使用。借助现成的配置模板，开发者无需从零摸索gdb与VS Code的对接细节，直接修改program路径即可启动调试会话；配套文档还介绍了变量观察、单步执行、条件断点与调用栈查看等常用调试技巧，帮助初学者更快理解Apollo复杂系统的运行逻辑，提升定位与解决问题的效率。无论是初步接触自动驾驶代码阅读，还是日常调试维护，这套配置都能显著降低上手门槛。

1. 折腾了一周，我总算把 VSCode 里的 GDB 断点调试在 Apollo 上车了

先给结论：在 VSCode 里断点调试 Apollo 代码，真正的难点不在 GDB 本身，而在于让 VSCode、容器里的编译产物、调试符号这三者在同一路径上对齐。Apollo 的代码几乎都在 Docker 容器里编译和运行，宿主机上的 VSCode 默认看不到容器内的文件系统和进程，这就导致很多人卡在「断点打上了但永远不命中」这一步。本文记录的就是我完整跑通「VSCode + GDB 调试 Apollo」的过程，包括环境准备、launch.json 配置、常见坑位和二次开发时怎么改配置。适合两类人：刚把 Apollo 下载下来、想搞清楚某个模块内部逻辑的初学者，以及需要在 Apollo 上做二次开发、想快速定位崩溃和逻辑错误的熟手。

2. 环境准备：容器、调试符号与 VSCode 扩展的三方配合

Apollo 的代码量很大，模块间通过自研的通信框架 CyberRT 交换消息，直接在生产环境目录里编译一份不带调试信息的二进制再跑去 gdb，大概率只能看到一堆??符号。所以第一步不是打开 VSCode，而是把调试环境按「容器内编译、容器内运行、VSCode 连接容器」的模型搭好。

2.1 Apollo 的容器运行模式，为什么不能直接在宿主机 gdb

Apollo 官方提供了一套基于 Docker 的开发环境脚本，宿主机只需要装 Docker，源码放在一个固定目录下，容器启动时通过 volume 挂载进去。常见的脚本入口是docker/scripts/dev_start.sh和dev_into.sh，前者负责创建并启动开发容器，后者负责进入容器内部的 bash。这种模式的好处是依赖隔离，坏处是调试时多了一层「容器边界」。

我在宿主机上直接尝试过gdb ./bazel-bin/modules/planning/planning，结果 gdb 确实能启动，但因为宿主机上没有容器内的共享库路径，动态库全部加载失败，程序刚跑起来就崩。后来换成了进入容器再调试，一次通过。这说明 Apollo 的 GDB 调试必须在容器内进行，否则你面对的是一堆无法解析地址的二进制。

容器模式下的调试链路大致是这样：

宿主机 VSCode ↓ 远程开发扩展 容器内的 VSCode Server ↓ gdb 容器内的目标进程

如果你的代码仓库是在一台 Linux 服务器上、而你用 Windows/Mac 本机编辑，中间还会多一层 SSH。我在实际项目中遇到的情况是：本机 Windows，服务器跑 Ubuntu，Apollo 源码放在服务器上，所以我用的是 VSCode 的 Remote-SSH 连到服务器，再通过 Dev Containers 附加到正在运行的 Apollo 容器。前一步容易踩坑，后面我会专门写一节。

2.2 编译选项：没有调试符号的 gdb 等于盲调

Apollo 的模块使用 Bazel 构建，默认的编译模式很可能是优化模式，调试时会发现局部变量被优化掉、函数调用栈对不上源码行号。要舒服地打断点，必须先确认目标模块是用带调试信息的模式编译的。常见做法是给 Bazel 指定编译模式：

# 在容器内，先进入 Apollo 根目录 bazel build //modules/planning:planning --compilation_mode=dbg

这里有几个参数值得说明。//modules/planning:planning是要构建的目标，路径对应源码目录下的 BUILD 文件定义；--compilation_mode=dbg告诉 Bazel 使用-O0 -g级别的编译参数，不优化、保留调试信息。如果你不加这个参数，Bazel 默认可能是fastbuild或opt，前者有部分符号但优化仍然存在，后者基本无法单步调试。

编译完成后还需要做一次验证，而不是直接启动 VSCode。我一般会用file命令看一下二进制：

file bazel-bin/modules/planning/planning

输出里如果带with debug_info字样，说明调试符号已就位。如果只显示stripped，建议检查刚才的编译模式是否真正生效，有时候因为 Bazel 缓存，用的还是旧产物，需要加--force或先bazel clean一次。这一步虽然看起来无关紧要，但它直接决定了后面断点会不会命中。

2.3 VSCode 扩展安装：Remote-SSH 与 Dev Containers 的边界

在 VSCode 里调试 Apollo，我的选择是装两个扩展：Remote - SSH 和 Dev Containers。前者负责把本机编辑环境连到远端服务器，后者负责让你从宿主机「附加」到一个正在运行的 Docker 容器中。两个扩展的边界经常被搞混，我一开始只用 Remote-SSH，结果发现容器里的文件在 VSCode 里看不见，因为 SSH 连接的是宿主机，文件路径是/apollo/modules/...，但宿主机上根本没有这个目录，源码是在容器挂载后才会出现的。

正确的姿势是：先通过 Remote-SSH 连到宿主机，然后打开 VSCode 的命令面板，执行Dev Containers: Attach to Running Container，选择 Apollo 那个容器。这样 VSCode 会在容器内启动一个 Server，左侧文件树看到的就是容器视角下的/apollo源码。之后所有调试配置里的路径，都以容器内路径为准。

如果把 Apollo 直接跑在本地 Linux 上，不需要 Remote-SSH，只要 Dev Containers 就够了。两种方式下 GDB 命令没有本质区别，唯一的差异是网络层多了一跳，调试响应会稍微慢一点，但完全可接受。

3. launch.json 配置实战：从一条 gdb 命令到可视化断点

环境就绪后，核心工作就是把 gdb 命令行翻译成 VSCode 的launch.json。很多初学者不愿意碰这个文件，觉得它是黑匣子。其实launch.json本质上就是把你手动敲的gdb --args ./binary拆成了结构化字段。

3.1 手动 gdb 跑通，作为 launch.json 的参照系

我强烈建议先把 gdb 手动运行一遍，确认程序能正常启动、环境变量正确。这一步能在最底层排除「容器、权限、共享库」这三座大山。在容器内执行：

source /apollo/cyber/setup.bash gdb --args /apollo/bazel-bin/modules/planning/planning

source是加载 CyberRT 的环境变量，相当于把动态库搜索路径和 Python 路径注入当前 shell。gdb --args后面的内容就是被调试程序的完整启动命令。如果这一条能正常进入 gdb 交互界面，输入run程序能跑起来，再输入Ctrl+C能中断，就可以继续。任何一步失败，都要先解决，不要带着问题进 VSCode，否则折腾半天也不知道是配置写错还是环境本身有问题。

3.2 手写一份可用的 launch.json：cppdbg 与 lldb 两种选择

VSCode 里调试 C++ 有两条路线：微软官方的 C/C++ 扩展（类型是cppdbg）和 CodeLLDB 扩展（类型是lldb）。Apollo 这种大型项目我推荐用 CodeLLDB，它对多线程和环境变量的处理更稳，UI 上查看 STL 容器内容也更直观。但如果你是在一个已经有 C/C++ 扩展的团队环境里，cppdbg 也完全够用。下面先给一份基于 CodeLLDB 的配置：

{ "version": "0.2.0", "configurations": [ { "name": "Apollo Planning Launch", "type": "lldb", "request": "launch", "program": "/apollo/bazel-bin/modules/planning/planning", "args": [], "cwd": "/apollo", "env": { "CYBER_LOG_LEVEL": "1" }, "initCommands": [ "settings set target.process-stop-on-exec true" ] } ] }

program 字段指向容器内编译出的二进制，args 是传给程序本身的命令行参数，cwd 建议固定为/apollo，因为很多相对路径配置文件依赖当前工作目录。env 里可以追加环境变量，比如我把CYBER_LOG_LEVEL设成1来减少日志输出。initCommands 会在 gdb 启动、程序加载前执行，这里的target.process-stop-on-exec是为了在 fork 出子进程时立即停下来，后面讲模块调试时会解释。

如果使用微软 C/C++ 扩展，配置长这样：

{ "version": "0.2.0", "configurations": [ { "name": "Apollo Planning Launch", "type": "cppdbg", "request": "launch", "program": "/apollo/bazel-bin/modules/planning/planning", "args": [], "stopAtEntry": false, "cwd": "/apollo", "environment": [ { "name": "CYBER_LOG_LEVEL", "value": "1" } ], "externalConsole": false, "MIMode": "gdb", "miDebuggerPath": "/usr/bin/gdb", "setupCommands": [ { "text": "-enable-pretty-printing", "ignoreFailures": true } ] } ] }

和 CodeLLDB 的差异主要在miDebuggerPath字段，它指定容器内 gdb 的绝对路径。如果你装的是 gdb 12，路径一般是/usr/bin/gdb，可以通过which gdb确认。setupCommands里的-enable-pretty-printing是打开 gdb 的 pretty-printer，不然看 STL 容器的内容会是一堆十六进制地址。

3.3 处理 Apollo 多进程模块：用 attach 代替 launch

Apollo 的模块大多不是孤立的，planning 模块需要感知上游 perception、prediction 的输出，而这一整套通常由一个 launch 脚本拉起。如果你直接 launch planning 二进制，它很可能因为拿不到数据而空转，断点自然不触发。这种场景的常见做法是：先正常运行整个流程，然后用 attach 模式挂载到已经跑起来的进程上

{ "name": "Apollo Planning Attach", "type": "cppdbg", "request": "attach", "program": "/apollo/bazel-bin/modules/planning/planning", "MIMode": "gdb", "miDebuggerPath": "/usr/bin/gdb", "processId": "${command:pickProcess}" }

processId 支持${command:pickProcess}，调试启动时 VSCode 会弹出进程列表，让你选一个。这一步需要留意：在 Apollo 容器里，一行命令可能会拉起多个同名进程，因为 CyberRT 内部可能用 mainboard 统一承载多个模块。按可执行文件路径过滤后，选择planning对应的 PID 即可。attach 模式的好处是不需要打断现有流程，坏处是如果目标进程频繁重启，PID 会变，每次都要重新选，二次开发时稍显繁琐。

4. 断点调试实操：从断点命中到调用栈分析

配置全部就绪后，下面进入真正的调试流程。这一章讲的是我在 Apollo 某个模块里排查一个偶发空指针的完整过程，虽然具体代码位置不能直接贴出来，但操作思路和 VSCode 里的交互方法是通用的。

4.1 设置断点的几种方式：行断点、函数断点和条件断点

在 VSCode 编辑器左侧点击行号位置，会出现红色圆点，这是最直观的行断点。Apollo 这类大型 C++ 项目里，我更常用的是函数断点：打开调试面板，选择C++调试类型后，在「断点」区域点击加号，输入函数名或类方法，例如OnLanePlanning::RunOnce。这种方法的好处是即使行号因代码变动而偏移，断点依然能落在函数入口。

条件断点是排查偶发问题的利器。比如你怀疑某个状态只在特定值下出错，在断点圆点上右键，选择「编辑断点」，输入条件表达式。以 planning 模块为例，如果你只关心 id 等于某个值的那一路规划请求，可以写：

id == 1024

这个表达式由 gdb 在断点处求值，为真才停下来。注意条件表达式里不能调函数，只能访问变量和运算。如果条件本身依赖的变量在当前作用域不可见，VSCode 会提示断点无法解析，这时候需要把断点往后挪到变量已经创建的位置。

4.2 调试控制台与 GDB 命令的配合

代码停在断点后，VSCode 顶部的调试操作栏有 Continue、Step Over、Step Into、Step Out、Restart、Stop 六个按钮。Step Over 是执行当前行但不进入函数内部，Step Into 则会进入函数体。规划类模块的函数嵌套很深，我通常先 Step Over 快速扫过外层，等接近疑似出错的逻辑时再 Step Into 进去。

更精细的查询是在「调试控制台」里直接敲 GDB 命令。Apollo 这种系统里，光靠 VSCode 的变量面板往往不够，因为变量面板有时刷新不及时，而调试控制台是实时直连 gdb 的。我常用的命令组合：

(gdb) bt (gdb) frame 2 (gdb) info locals (gdb) p this->current_scenario_ (gdb) thread apply all bt

bt打印当前线程的调用栈，frame 2切换到栈上第 3 层函数，info locals显示当前栈帧的所有局部变量，p是 print 的简写，直接查看对象内部字段。thread apply all bt在多线程程序里特别有用，能一次性把所有线程的调用栈打印出来，排查死锁和线程空指针时比逐个 thread 切换高效得多。

4.3 从缓存数据出发反推产生路径

有一次遇到的现象是：二次开发时给某个状态增加了一个新字段，程序跑到某个位置突然 SIGSEGV。断点打在赋值行，变量面板显示当前对象地址是0x0，说明空指针是在更早的地方产生的。此时直接往上找赋值来源很费劲，正确的做法是在空指针出现的上一级函数入口打一个断点，用watch观察这个地址何时被改掉：

(gdb) watch this->ptr_field_

执行continue后，gdb 会在该变量的值发生变化时自动停下，这样能精准抓到第一次置空的位置。虽然 VSCode UI 上也有「监视」功能，但面对this指针偏移这类低级问题，gdb 命令行里的watch更可靠。找到置空代码后，再回头检查那条路径的条件判断，最终定位到我在上一个版本中漏加的一个初始化步骤。

这个过程中有一个值得记住的技巧：全局搜索「谁改了这个字段」永远不如用 watch 让调试器告诉你。

5. 避坑指南：Apollo 调试过程中最常翻车的 4 个环节

前面把顺利路径走了一遍，这一章集中写我在真实环境中踩过的坑。每一条都是「现象 → 原因 → 解决」的结构，如果你在调试时卡住，优先对照这里排查。

5.1 断点显示已设置但始终不命中

现象：红色断点一直在，代码明确执行到了那一行，但调试器就是不暂停。有时候还伴随 VSCode 右下角提示「Breakpoint not yet installed」。

原因：最常见的是二进制和源码不同步。Apollo 默认编译可能是fastbuild，这类产物里有符号但优化严重，行号映射和源码对不上。另一种情况是 Bazel 复用缓存，你以为重新编译了，实际拿到的是旧文件。

解决：强制用 dbg 模式重新构建目标，并确认产物 mtime 是刚刚生成的：

bazel build //modules/planning:planning --compilation_mode=dbg ls -l --time-style=full-iso bazel-bin/modules/planning/planning

如果时间戳没变，先bazel clean再重新编译。另外，在 VSCode 里启动调试后，打开调试控制台输入info sources，检查当前加载的源文件路径是否和你打开的文件路径一致。

5.2 gdb 报错 ptrace: Operation not permitted

现象：点击调试后，VSCode 直接报ptrace: Operation not permitted，程序根本没启动。容器外用 gdb 没问题，进了容器就报这个。

原因：Docker 默认限制了容器内进程对 ptrace 的使用。Apollo 的容器如果是以普通模式启动的，gdb 无法 attach 或者被调试的进程。

解决：需要在容器启动时放宽权限，常见做法是重新启动容器时给 Docker 加上--cap-add=SYS_PTRACE。Apollo 的dev_start.sh会读取环境变量，有些版本支持配置PULL_IMAGE或GEOLOC；更直接的办法是在你的 docker run 命令中追加：

docker run -it \ --cap-add=SYS_PTRACE \ --security-opt seccomp=unconfined \ -v /path/to/apollo:/apollo \ your-apollo-image

seccomp=unconfined能避免容器安全策略拦截 gdb 的系统调用。这个配置只建议在开发容器上使用，生产环境不要这么干。

5.3 启动调试后程序立即退出，exit code 127

现象：launch.json 配置完成后，点击开始调试，程序立刻退出，调试控制台显示During startup program exited with code 127。

原因：动态库没找到。Apollo 的模块依赖大量.so，这些库的路径通过cyber/setup.bash注入，而 VSCode 调试时默认不会加载你 shell 里的LD_LIBRARY_PATH。

解决：有两种做法。第一种是在 launch.json 的environment字段里手动加：

{ "name": "LD_LIBRARY_PATH", "value": "/apollo/bazel-bin/cyber:/apollo/bazel-bin/modules/planning" }

第二种是更省事的方案：启动调试前，先进入容器并source /apollo/cyber/setup.bash，然后从同一个终端启动 VSCode。如果 VSCode 是图形界面启动的，可能仍然读不到环境变量，那就把 source 命令写在/root/.bashrc里，确保登录容器时自动注入。

5.4 调用栈里全是问号和偏移地址

现象：断点命中，但调试控制台bt输出看不到函数名，只有0x7f3a2c1d0b40 in ?? ()。

原因：二进制被 strip 了，或者加载的不是当前编译的调试版本。还有一种很隐蔽的情况：程序是动态链接的，函数体在另一个.so里，而那个.so没有调试符号。

解决：先用file查看二进制是否stripped，如果是，说明编译配置有问题，重新按 dbg 模式编译。如果是动态库缺符号，在 gdb 里用set solib-search-path /apollo/bazel-bin指定共享库搜索路径，让调试器找到对应.so的符号文件：

(gdb) set solib-search-path /apollo/bazel-bin (gdb) sharedlibrary

sharedlibrary会强制重新加载所有动态库的符号表。Apollo 多模块架构下，这个命令基本是必用的，尤其是当你调试的模块调用了 cyber 或者 common 目录下的代码时。

6. 二次开发改造思路：让调试配置成为模块开发的起点

走到这里，你已经能在 VSCode 里断点调试 Apollo 的某个模块了。接下来最有价值的改造，是把这一套调试配置模板化，让它服务于你后续的每一个模块开发。

我的习惯是维护一份名为apollo.debug.conf.json的公共配置片段，里面包含几组标准配置：一组 launch 模式用于独立启动单个模块，一组 attach 模式用于挂载已运行的流程，一组专门跑单测二进制：

{ "name": "Apollo Module Unit Test", "type": "lldb", "request": "launch", "program": "/apollo/bazel-bin/modules/planning/planning_test", "args": ["--gtest_filter=*Scenario*"], "cwd": "/apollo" }

二次开发新模块时，只需要复制对应配置，替换 program 路径和 args，不需要每次都研究字段含义。但我建议不要直接改这份公共配置，而是在每个模块目录下维护一份.vscode/launch.json，因为模块之间的参数差异会越来越大，混在一起容易改乱。

新增模块的调试还有一个实操技巧：先用 gdb 命令行的--args方式跑一遍，确认无误后再同步到 launch.json。我在给某个新模块配置调试时，习惯先在终端敲：

gdb --args bazel-bin/modules/my_module/my_module --flagfile=modules/my_module/conf/my_module.conf

验证能跑通后，把--flagfile=...原样搬进 args 数组。这样可以避免在 VSCode 界面里反复试错，尤其是参数里带相对路径的时候，环境变量和 cwd 的问题在命令行下暴露得更快。

从那以后，我每次给 Apollo 模块加调试配置，都强制走一遍「命令行 gdb 先跑通 → 再映射到 launch.json → 最后用 attach 验证多进程场景」的流程，再也没有被调试器本身的问题打断过。希望这个流程也能帮到你少走点弯路。

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