简介面向Apollo PnC开发者的基础项目包聚焦规划与控制模块的工程实践。该资源围绕路径规划、轨迹生成、车辆控制、感知融合与实时性能等核心环节清晰展示PnC模块在自动驾驶框架中的职责边界与协作方式适合想深入理解Apollo PnC架构并开展定制化开发的工程师。包内共12个文件以json配置、xml工程描述、build构建脚本、workspace工作区定义为主另有env环境变量、clang-format代码风格、conf配置等辅助文件整体仅7KB轻量却覆盖项目骨架。目前已有513人学习。通过梳理application-pnc-main的目录结构与模块接口读者可快速定位配置文件、构建脚本和环境定义掌握配置管理、源码阅读与调试方法为后续扩展与实车验证打下基础。1. Apollo PnC 基础项目先跑通链路再谈看懂代码新同事第一次拿到 Apollo PnC 基础项目时最容易犯的错是打开规划模块源码往下啃几个晚上过去还没弄清楚轨迹消息从哪来、控制模块到底在跟踪什么。我的习惯相反先把整个 PnC 链路在 Docker 里跑起来让仿真车动起来完整看一次从感知到规划再到控制的闭环然后才动手找代码入口。这个基础项目的价值不在于让你读完几十个规划算法而在于给你一条最短的可改动链路——你能在仿真里看到目标轨迹能关掉某个策略看变化能把巡航速度从 30 提到 60。适合刚接触 PnC 的开发者和自动驾驶方向的在校学生如果你已经带过完整量产项目可以直接跳到排障章节。2. 把这个 PnC 基础项目跑起来的正确姿势从 Docker 到 DreamView2.1 为什么 PnC 开发绕不开 Docker依赖一致性才是第一生产力PnC 模块表面上只是一个规划器加一个控制器但它背后的依赖链一点都不少。Cyber RT 的编译环境、Protobuf 版本、Eigen 版本、OSQP 求解器还有地图工具链任何一个库的版本不匹配编译阶段报出来的错误都很容易让人误以为是代码逻辑问题。更隐蔽的是某些库版本不匹配时能编过但跑起来数值异常——轨迹点直接跳变控制模块以为目标点在十几米外方向盘猛打一下观感相当惊悚。Docker 在这里的作用不只是“隔离”这么简单它把整个工具链锁进一个镜像里。镜像里是什么版本所有开发者拿到手就是什么版本。我一般让新人在容器内编译物理机上除了 Docker 和浏览器什么都不要装。这样做最大的好处是出了问题时你能确定问题出在代码层还是环境层而不是先花两天排查“为什么我编不过而文档里说能编过”。2.2 拉代码装环境一次进入容器的完整操作拿到基础项目的第一步是从代码仓库拉取 Apollo 源码并进入开发容器。不同版本入口脚本略有差异但常见做法是一套dev_start加dev_into的组合。git clone apollo代码仓库地址 apollo cd apollo bash docker/scripts/dev_start.sh bash docker/scripts/dev_into.sh第一行拉取源码第二行进入仓库根目录。dev_start.sh会检查本地是否已有开发镜像没有就先拉取然后启动一个挂载好代码目录的容器首次执行会持续较长时间取决于网络和镜像大小。dev_into.sh是进入正在运行的容器容器内代码目录通常在/apollo。进入容器后第一件事是编译。基础项目阶段不需要全量构建所有模块但为了确保后续依赖完整常见做法是先做一次全量编译之后再按模块增量编译。cd /apollo bash apollo.sh build这条命令会依次完成依赖检查、proto 生成和模块编译。首次编译消耗比较大内存建议不低于 8G编译时间在十几分钟到数小时不等。看到Build passed之类的输出后环境就算通了。提示如果物理机内存紧张云主机编译会卡在链接阶段。至少保证 8G 内存和 2 核以上磁盘剩余空间 20G。2.3 启动 DreamView 与仿真器第一次看到 PnC 在跑编译完成后启动可视化平台 DreamView。它既是可视化工具也是仿真控制台PnC 调试的大部分操作都在这里完成。cd /apollo bash scripts/bootstrap.sh start启动后在浏览器里打开本机的 8888 端口进入 DreamView 界面。第一次进入时在左侧模式选择里选 Simulation 模式地图选自带的基础地图。如果你拉取的版本里地图列表为空检查地图数据目录是否构建完整这个问题在排障章节会细说。接下来打开 Sim Control 面板。这个模式会模拟底盘、定位和感知信号不需要真实车辆就能让 PnC 链路跑起来。在 Sim Control 模式下车默认停在某个位置你可以在界面上用 Routing Editor 画一条从当前位置到目标点的路由。画完后车开始沿路由行驶屏幕上会出现两条曲线一条是参考线另一条是规划模块实时输出的目标轨迹。看到绿色轨迹线跟着车走说明从规划到控制的最小链路已经通了。到了这一步你已经有了一个能跑的基础环境。不要急着改代码先花十分钟在 DreamView 里切不同视角看看轨迹线在直道和弯道上分别长什么样。这个直观印象比读十篇论文都有用。2.4 项目目录结构PnC 代码到底躺在哪里对 PnC 开发来说代码主要集中在两个目录规划模块和控制模块。下面是一份常见目录结构可以作为定位代码入口的地图。apollo/ ├── modules/ │ ├── planning/ │ │ ├── conf/ # 规划模块配置文件 │ │ ├── scenarios/ # 场景管理器 │ │ ├── tasks/ # 决策与轨迹生成子任务 │ │ ├── common/ # 参考线、坐标转换等公共逻辑 │ │ └── proto/ # 规划消息的 proto 定义 │ ├── control/ │ │ ├── conf/ # 控制器参数 │ │ ├── controller/ # LQR、MPC、PID 等控制器实现 │ │ └── proto/ # 控制消息定义 │ ├── common/ # 公共库 │ ├── map/ # 地图数据与工具 │ └── ... └── scripts/ # 仿真、启动、打包脚本不同版本的 Apollo 目录细节有调整但conf放配置、controller放控制算法、scenarios放场景策略这个基本划分是稳定的。基础项目阶段你不需要看懂全部目录核心记住一条planning 的conf是后面改参数的主要阵地control 的conf是搞定车辆跟踪品质的关键。两个目录下的.conf文件都用文本格式存储改动后需要重启对应模块才能生效。3. PnC 链路拆解从感知消息到控制指令基础项目里的数据长什么样3.1 规划模块在做什么从路由到一条可跟踪的轨迹规划模块的输入远比想象中多。它要拿到路由信息才知道往哪开要拿到地图和定位信息才知道自己在哪条车道上要拿到感知障碍物列表才知道哪里有风险还要拿到预测模块的输出才知道障碍物接下来怎么动。所有这些输入经过场景管理器分流落到具体的决策器里最终产出一条带时间戳的目标轨迹。这条轨迹不是一串坐标点而是一个包含位置、速度、加速度、航向角和曲率的序列。控制模块拿到它之后才能算出方向盘打多少、油门给多少。在基础项目里你可以把规划模块理解成一个“翻译器”把路况和任务翻译成一条车能跟的轨迹。在 DreamView 里看到绿色轨迹线时注意观察它在障碍物附近的形状。直道上的轨迹会平滑地绕开障碍物而不是折线式跳变。如果轨迹出现折角通常是参考线质量问题或某组规划参数设置过激这是后面调参时的重要观察点。3.2 控制模块在做什么不是踩油门刹车而是轨迹跟踪控制模块做的事情看起来很简单——车按照规划轨迹走。但“按轨迹走”这件事拆开后包含两条控制回路横向控制管方向让车横向偏差趋近于零纵向控制管速度让车速贴合轨迹上的建议速度。横向控制常用的算法有 LQR、MPC纵向控制常见的是 PID 或带前馈的速度控制器。基础项目里控制模块大多不需要改代码但你要能从日志里区分出“规划轨迹跳了”和“控制器没跟上”这两种情况。前者的典型特征是轨迹线本身异常后者的典型特征是轨迹线正常但车偏离轨迹横向误差持续增大。记住这个判断顺序先看轨迹线对不对再看车跟没跟上。大多数入门阶段遇到的诡异问题最后都出在轨迹线本身不对而不是控制器失控。3.3 用 cyber_monitor 看 PnC 消息流cyber_monitor是 Cyber RT 自带的话题监视工具作用类似 ROS 里的rostopic echo。进入容器后直接启动。cd /apollo bash cyber_monitor启动后是一个交互式界面用方向键在频道列表里上下移动回车展开消息内容。重点看两个频道/apollo/planning和/apollo/control。前者是规划模块输出的目标轨迹后者是控制模块最终发出的控制指令。实际操作一下在 Sim Control 模式下让车跑起来在 cyber_monitor 里展开/apollo/planning你会看到一长串trajectory_point。每个点里有坐标、速度、加速度和相对时间。这些字段构成了一条完整的轨迹。刚开始看会觉得很碎但这是排障的基础能力——当 DreamView 里看不到轨迹时你只能靠这里的数据判断规划模块到底有没有输出。3.4 一条轨迹消息的字段解读别把它当黑匣子打开一条 planning 消息后你看到的字段是有规律的。下面这张表列出了最常用的几个字段和它们的用途。字段含义使用场景trajectory_point.path_point.x / y / z轨迹点的全局坐标可视化、判断是否偏离车道trajectory_point.path_point.theta该点的航向角控制模块前馈角度trajectory_point.path_point.kappa该点的曲率弯道限速、舒适性评估trajectory_point.v建议速度纵向控制的目标速度trajectory_point.a建议加速度舒适性与纵向控制trajectory_point.relative_time距轨迹起点的相对时间控制模块预瞄与插值一个容易混淆的点是relative_time。它不是时间戳而是从轨迹起点开始算的相对时刻通常从 0 递增。控制模块拿到轨迹后会根据当前时间和这个字段做插值找到当前应该跟踪的点。你在数据里看到relative_time: 0.1意味着这是 0.1 秒后的目标点而不是某时刻的 Unix 时间。理解这些字段之后你会发现 PnC 的数据链路并不神秘规划模块输出一串带时间和速度的点控制模块跟踪这一串点。调试的基本功就是频繁在这份数据里核对“规划有没有输出”“输出是否符合常理”。4. 把巡航速度从 30 提到 60PnC 基础项目里的第一个参数改动4.1 在 Sim Control 里布置一条带障碍物的直道改参数前先构造一个可重复验证的场景。在 DreamView 的 Sim Control 面板里把车拖到一条长直道的起点位置再在距离起点一段距离的车道中间放置一个静态障碍物。放置后障碍物会以可感知的形式出现在地图上。然后用 Routing Editor 画一条从起点到直道尽头的路由。画完后车开始行驶正常情况是车先加速到巡航速度接近障碍物时减速并绕行越过障碍物后重新加速。这个场景包含了巡航、避障、回正三段典型工况非常适合验证速度类参数。场景构造好后先跑一遍确认当前状态下全程无异常。然后停下车准备开始第一次参数改动。任何参数调试都要从“改前可复现、改后可对比”出发否则改动是否生效只能靠感觉判断。4.2 用 gflags 和 conf 文件定位参数而不是上来改代码PnC 模块的很多参数并不写在代码里而是通过 gflags 机制从 conf 文件加载。gflags 的加载逻辑是代码里声明一个带默认值的变量程序启动时读取配置文件里对应的行用配置文件的值覆盖默认值。这种设计让参数调试不需要重新编译是基础项目里最高频的改参路径。以巡航速度为例规划模块里通常有一个名为default_cruise_speed的 gflags 参数。先确认它在代码里的存在位置和默认值。cd /apollo grep -rn default_cruise_speed modules/planning --include*.cc --include*.h命令会在规划模块源码里找出所有引用这个参数的的地方。你会看到它被用于设置默认巡航速度的初始值。接着再看配置目录里有没有对应项。grep -rn default_cruise_speed modules/planning/conf/如果 conf 目录下没有这个关键词说明该参数没有在配置文件里显式声明使用的是代码里的默认值。这正好解释了为什么只改代码没用、改配置也未必有用——必须确认参数当前到底从哪里取值。4.3 修改巡航速度参数并重启规划模块找到参数后在对应的 conf 文件中加入或修改这一行。Apollo 的 gflags 配置文件格式是每行一个参数参数名前带两个短横线。--default_cruise_speed16.67说明一下单位换算默认值常见是 8.33 m/s约等于 30 km/h改成 16.67 m/s约等于 60 km/h。弯道上的实际速度不会达到这个值因为规划模块里还有曲率限速逻辑在兜底但这能让直道上的巡航速度明显提升。修改配置文件后需要重启规划模块才能生效。最稳妥的方式是在 DreamView 右侧 Module 面板里对 Planning 模块执行 Restart。也可以在容器内找到并重启 planning 进程但 DreamView 的操作更直观适合刚上手时使用。提示gflags 配置文件里参数名带--前缀这和 YAML 或 JSON 的写法不同。手动新增配置时不要把前缀漏掉否则会被解析成另一个参数。4.4 验证改动效果看速度剖面而不是只看“车变快了”重启 Planning 后重新跑同一个场景。确认车在直道上的平稳速度确实提升到了接近 16 m/s同时还要观察绕行障碍物时的减速行为是否合理。如果减速度过大、车辆出现明显点头动作说明速度限制改得太激进或者舒适性相关参数还没有跟上。更严格的验证方式是从 cyber_monitor 里读取轨迹点的速度值展开/apollo/planning看直道段的v字段是否稳定接近 16 左右。只看仪表盘时速容易忽略规划层是否真正输出目标速度——如果规划层输出还是 8车即使看起来快也可能是控制模块临时响应过一会就会回落。到这里你已经完成了第一个 PnC 参数改动。这个流程——定位参数、修改配置、重启模块、对比验证——会贯穿此后几乎所有 PnC 调参工作。对比数据要有存档最简单的方式是每次改动前后用 cyber_monitor 记录一组轨迹速度后面查问题时有后悔药。5. Apollo PnC 基础项目排障五个高频坑与必查清单基础场景打通之后接下来遇到的大多是重复出现的问题。下面五个坑是入门阶段最高频的每条按现象、原因、解决三个步骤拆开方便你直接对照排查。5.1 现象DreamView 能打开但地图区域一片黑现象浏览器能进入 DreamView模式也能选但地图区域全黑路网没有渲染出来。原因常见有两种。一是地图数据没有完整生成首次启动时地图进程还在加载底图或者地图数据目录不完整二是浏览器缓存了旧的静态资源把上一次未加载完成的状态记住了之后每次打开都复现黑屏。解决先等半分钟看地图是否自动出现。没出现就检查容器内地图相关的日志有无报错。日志正常时在浏览器里做一次强制刷新快捷键是 Ctrl/Cmd Shift R绕过缓存重新拉取资源。大多数黑屏问题到这一步就解决了。如果还黑着检查是否同时启动了多个 DreamView 实例只保留一个再试。5.2 现象容器内编译到规划模块时报 Eigen 版本冲突现象执行bash apollo.sh build编译到某个依赖时提示 Eigen 版本不对或者第三方库找到的路径指向物理机的目录。原因物理机上之前装过 ROS 或其他依赖 Eigen 的框架设置过CMAKE_PREFIX_PATH这类环境变量。进入容器后部分环境变量被继承下来CMake 找到了物理机上的库而不是镜像里自带的版本。这类问题在入门环境里极其常见现象又很像代码问题容易误导排查方向。解决先在容器里执行env | grep -E CMAKE|EIGEN|ROS确认环境变量是否干净。有继承进来的变量时手动unset掉再重新编译。更彻底的方案是放弃物理机上的重复依赖所有编译动作都只在容器内做。如果已经留下被污染的编译缓存删除构建目录后重新编译。5.3 现象仿真车停在原地日志里循环报 No valid trajectory现象Sim Control 模式下车辆就位路由也画了但车不动。打开规划模块日志反复出现找不到有效轨迹的提示。原因这一条的原因通常是路由没有真正生效或定位模块输出的车辆位置和路由起点不匹配。逻辑上规划模块必须有完整输入才会输出轨迹任何一个输入缺失都会表现为“无有效轨迹”只看规划日志定位不到根因。解决按输入顺序排查。先看路由是否生成DreamView 里应有一条从起点到终点的绿色路线再看定位是否收敛仪表盘上的车辆位置是否落在车道上最后看规划可视化正常情况下应能看到输出轨迹。三步走完卡在哪一步就在那一步继续深入。切忌反复重启规划模块——它只是结果不是原因。5.4 现象改了 conf 文件回到 DreamView 发现车速没变现象按第 4 章的方法改了巡航速度也保存了文件但跑起来速度依然不变。原因规划模块还跑着旧进程。gflags 配置只在模块启动时加载一次不是热加载即使模块内部有周期更新机制这部分参数也不会自动重读。在 DreamView 界面里直接继续驾驶看到的一定是旧参数下的行为。解决在 DreamView 右侧 Module 面板里对 Planning 执行 Restart或者进入容器手动重启规划进程。重启后重新运行场景。如果速度还是没有变化回到 4.2 用 grep 确认你改的 conf 文件确实被当前流程加载而不是另一个同名不同路径的文件。5.5 现象Sim Control 里放了障碍物车却直接压过去现象在 Sim Control 面板把障碍物拖到车道中间但车靠近时既不减速也不绕行直接从障碍物位置穿过去。原因Sim Control 里放置的障碍物如果只是被当成背景元素就不会进入规划模块的障碍物列表。规划模块没有收到障碍物消息自然不知道前面有东西。这属于输入缺失不是规划算法不避障。解决切到感知可视化视角看障碍物是否出现在感知结果中。如果没有出现检查感知模块是否正常运行或者改用 Sim Control 的虚拟障碍物功能让障碍物直接发布到感知话题里。在入门阶段确保“障碍物真的被感知看到”比调任何避障参数都重要。6. 从基础项目走向 PnC 工程习惯给改动留后悔药基础项目能跑通、会改参数之后下一步不是多跑几个场景而是建立一套让自己能回退的习惯。PnC 调参不像写业务代码编译通过不代表行为正确一个参数改下去可能直道变好、弯道变差。所以我现在改任何 PnC 参数第一件事不是动手改而是先记下当前版本的行为基线。我一般维护三个固定场景一段直道、一段连续弯道、一段带静态障碍物的道路。每个场景跑一遍记录三个数直道上的巡航速度、弯道里的最大横向误差、绕障时的最小离障碍物距离。这三组数据构成一个迷你回归集每次改动前后各跑一遍对比结果比任何代码评审都更能暴露问题。配套的习惯是给每次改动建一个独立分支提交信息里写清楚改了什么参数、预期影响是什么、实测数据和预期是否一致。A同学当时改了纵向控制参数直道上提速非常明显他高兴地没跑弯道场景就合入了改动结果连续弯道里车频繁急刹乘员体验一塌糊涂。这件事之后我们约定俗成任何 PnC 参数改动至少过一遍上面三个场景再谈合入。另一个值得养成的习惯是善用 cyber_monitor 留数据。跑场景前把规划轨迹的关键字段记录下来跑完再做一次对比。轨迹速度、横向误差、相对时间这些字段能告诉你改动到底改变了什么。时间久了你会发现PnC 调试里所谓“玄学”绝大多数其实是没留对比数据造成的错觉——车变快了但你没记下快多少、在哪一段快、牺牲了什么。基础项目的最后一个练习我建议你试着把巡航速度参数改回默认值重复第 4 章的整个验证流程然后对比两次轨迹数据。能完成后你对 PnC 的认知就不是“一个黑盒”而是一条可以定位、可以改动、可以回退的确定性链路。希望帮到你。本文还有配套的精品资源点击获取