ROS2_learn/.docs/bug_logs/2026-08-04_quickstart_audit.md

Quickstart 文档审计 & Bug 修复报告

审计时间: 2026-08-04 审计员: 模型 MiniMax-M3(以"完全零基础小白"身份执行 README+doc/01-quickstart 的"30 分钟跑通 Hello World"全流程) 审计方法: 按文档命令逐字执行,把每一步实际操作结果记录下来。

---

TL;DR

按 README.md 和 doc/01-quickstart.md 原样 走一遍,至少 5 个严重 bug 会卡住小白:

#	位置	现象	严重度	修复
1	README.md:92 步骤 5	docker run -d ... ros2-humble-dev:latest 缺保活命令,容器立刻 Exited (0)	🔴 P0	✅ 改文档 + 加 bash 参数,或让脚本包办
2	README.md:130 步骤 7	教小白跑 ros2 --version — 这个选项不存在,会报 unrecognized arguments: --version	🟡 P2	✅ 改文档
3	README.md:194 步骤 10	ros2 launch py_pubsub pubsub_launch.py — launch 文件不在 py_pubsub,实际在 bringup/launch/pubsub_launch.py	🔴 P0	✅ 改文档
4	doc/01-quickstart.md:166-167 步骤 4.2	教小白跑 bash build.sh — 仓库根根本没有 build.sh,文件不存在	🔴 P0	✅ 新增 scripts/build.sh 修复
5	bringup/launch/pubsub_launch.py:38	launch 把 2.0(double) 传给 C++ 节点 publish_rate_hz(int 参数),C++ 进程 crash Wrong parameter type	🔴 P0	✅ 改 C++ 节点声明对齐 Python:double
6	README.md vs doc/01-quickstart.md 整体	两份文档教小白两条完全不同的上手路径(手动 docker run vs docker compose),小白不知道跟谁	🟡 P1	📝 文档风格统一(待办)
7	scripts/*.sh(新建)	set -euo pipefail 跟 ROS 官方 setup.bash 不兼容(AMENT_TRACE_SETUP_FILES 未定义)	🟡 P2	✅ 已修(改 set -eo pipefail)

剩余所有 bug 已修复或文档已更正,12 包 / 78 测试(64 pytest + 14 gtest)/ 跨语言互通全部跑通。

---

详细记录

Bug 1 — README 步骤 5:容器立刻退出(已修)

原文档:README.md line 92

docker run -d --name ros2_dev -v "${PWD}:/root/ros2_ws" --network ros2_net ros2-humble-dev:latest

实际跑结果:

CONTAINER ID   IMAGE                      NAMES      STATUS
6fe266def5c0   ros2-humble-dev:latest      ros2_dev   Exited (0) 31 seconds ago

根因:

• 基础镜像 osrf/ros:humble-desktop 的 default ENTRYPOINT = ros_entrypoint.sh,会 source /opt/ros/humble/setup.bash 后 exec bash
• Dockerfile 自定义 CMD ["bash"],所以最终容器跑起来是 bash
• docker run -d 没指定 tty/stdin,bash 立刻检测 stdin 关闭 → exit 0
• 而 docker-compose.yml 用 command: ["bash", "-lc", "tail -f /dev/null"] 给容器保活

修复:

1. README 把命令改成:docker run -d -it --name ros2_dev -v "${PWD}:/root/ros2_ws" --network ros2_net ros2-humble-dev:latest bash (挂后台 + 给 bash 命令保持运行)
2. 或干脆统一走 docker compose,让用户跟 make up / make shell 一致
3. 并且为用户补齐 scripts/shell.sh 一行命令进入开发终端

Bug 2 — README 步骤 7:ros2 --version 不存在(已修)

原文档:README.md line 130

ros2 --version   # 应该显示 ROS 2 package version 1.0 (or similar)

实际跑结果:

ros2: error: unrecognized arguments: --version

修复: 改用 dpkg -l ros-humble-rclcpp | tail -1 或 ros2 --help | head -5,或者直接砍掉这步(在第 8 步编译成功就已足够证明 ROS2 装好)。

Bug 3 — README 步骤 10:launch 包名错(已修)

原文档:README.md line 194

ros2 launch py_pubsub pubsub_launch.py

实际跑结果:

Package 'py_pubsub' not found, ... unable to find launch action 'pubsub_launch.py'

(注: py_pubsub 下也有 launch/pubsub_launch.py,但 launch 文件只在 build/install 后才被 find,需要先 colcon build;但用户已经 build 过。这里实际可用 ros2 launch bringup pubsub_launch.py,因为 bringup 包才是 4 节点跨语言版本)

修复: 改文档 ros2 launch bringup pubsub_launch.py

Bug 4 — doc/01-quickstart.md 步骤 4.2:build.sh 不存在(已修)

原文档:doc/01-quickstart.md line 166

bash build.sh

实际跑结果:

bash: build.sh: No such file or directory

根因: 文档假设存在一个项目根的 build.sh 聚合脚本,但仓库只产了 Makefile(走 docker compose)或 README 给的 colcon build(直接命令)。

修复: 新增 scripts/build.sh 修复文档承诺:

• 接受 WORKSPACE 环境变量
• 自动 source ROS2 + colcon build 12 个包
• 后续 scripts/test.sh / scripts/launch.sh / scripts/clean.sh 同一规范

Bug 5 — bringup/launch/pubsub_launch.py C++ 节点 crash(已修)

原报错 (实际跑 launch 时):

[chatter_publisher_cpp-2] terminate called after throwing an instance of
'rclcpp::exceptions::InvalidParameterTypeException'
[chatter_publisher_cpp-2] what():  parameter 'publish_rate_hz' has invalid type:
  Wrong parameter type, parameter {publish_rate_hz} is of type {integer},
  setting it to {double} is not allowed.
[ERROR] [chatter_publisher_cpp-2]: process has died [pid ..., exit code -6]

根因:

• cpp_pubsub/src/chatter_publisher.cpp:22 声明 declare_parameter<int>("publish_rate_hz", 2, ...)
• bringup/launch/pubsub_launch.py:38 通过 parameters=[{... 'publish_rate_hz': 2.0 ...}] 传 double
• C++ 节点启动时调用 set_parameter 检查类型不匹配 → 抛异常 → terminate called

修复: publish_rate_hz 改成 double(对齐 py_pubsub),语义 Hz 可以是 1.5、0.5 这种小数,int 不合理。

涉及文件:

• src/cpp_pubsub/src/chatter_publisher.cpp: declare_parameter <double> + .as_double() + 周期计算加 static_cast<int>
• src/cpp_pubsub/test/test_pub_sub.cpp: as_int() → as_double() + EXPECT_DOUBLE_EQ(..., 2.0)

Bug 6 — 文档两条上手路径矛盾(待修,优先级中)

README.md (从零 30 分钟) 教小白:

• 步骤 4:docker build -t ros2-humble-dev:latest -f docker/Dockerfile .
• 步骤 5:docker run -d --name ros2_dev ...
• 步骤 6:docker exec -it ros2_dev bash
• 步骤 8: cd /root/ros2_ws && colcon build --symlink-install

doc/01-quickstart.md (5 分钟 Quickstart) 教的是另一套:

• Step 2.2:docker compose -f docker/docker-compose.yml build
• Step 3: docker compose -f docker/docker-compose.yml up -d
• Step 4.2:bash build.sh(根本不存在)
• 然后才讲ros2 launch bringup pubsub_launch.py

修复方向: 二选一:

• A) README 完全改成 make up / make shell / make colcon-build(跟 Makefile 对齐)
• B) doc/01-quickstart 完全删掉(README 是入口)

已采取: 先用脚本 (scripts/*.sh) 跟 Makefile 等价,无论走哪条路都能复用。然后改 README 步骤 5 加 -it 和保活命令,并删掉错误的 ros2 --version、py_pubsub pubsub_launch.py。

Bug 7 — set -u 跟 ROS setup.bash 不兼容(已修)

实际跑结果 (首次 bash scripts/build.sh):

/opt/ros/humble/setup.bash: line 8: AMENT_TRACE_SETUP_FILES: unbound variable

根因: ROS 官方 setup.bash 默认不严格,有许多只在 trace 模式下读取的变量;set -u 在非 trace 下读这些变量会炸。

修复: 把 set -euo pipefail 改成 set -eo pipefail(保留 -e 严格错误检测,放弃 -u 未定义变量)。

---

"Test-After-Fix" 验证

步骤	命令	结果
编译	docker exec ros2_dev bash scripts/build.sh	✅ Summary: 12 packages finished [1min 45s]
测试	docker exec ros2_dev bash scripts/test.sh	✅ Summary: 78 tests (64 pytest + 14 gtest), 0 errors, 0 failures, 0 skipped
启动	docker exec ros2_dev bash scripts/launch.sh pubsub_launch 15	✅ 4 节点全起,跨语言互通:C++ subscriber 收到 Hello from PY 和 Hello from C++

---

后续 TODO(优先级降序)

1. ☐ README.md 整体改写,统一走 docker compose/make 路径(避免和 doc/01 二选一)
2. ☐ doc/01-quickstart.md 整篇精简为 README 索引
3. ☐ scripts/ 加 PowerShell 入口 (make_up.ps1 / make_shell.ps1),让 Windows 小白不用装 make
4. ☐ AGENTS.md 增加 "bug 修复记录写 docs/bug_log/YYYY-MM-DD.md" 规则