ROS工作空间catkin_make常见问题排查

ROS1 开发中，catkin_make 是最常用的工作空间编译命令。对于刚开始写 ROS 包的开发者来说，编译失败、找不到包、消息未生成、Python 节点不能执行等问题非常常见。

本文整理 catkin_make 工作空间的基本结构、常用命令和排查思路，帮助快速定位编译问题。

标准工作空间结构

一个典型 catkin 工作空间：

catkin_ws/
  src/
    demo_pkg/
      CMakeLists.txt
      package.xml
      src/
      scripts/
      msg/
      srv/
  build/
  devel/

src 存放源码包，build 和 devel 是编译生成目录。通常只需要把 src 下的包提交到 Git，build 和 devel 不提交。

创建工作空间：

1
2
3

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make

编译成功后加载环境：

1	source devel/setup.bash

如果每次打开终端都要使用该工作空间，可以加入 ~/.bashrc：

1	source ~/catkin_ws/devel/setup.bash

找不到包

运行节点时报错找不到包：

1	rospack find demo_pkg

如果找不到，检查：

包是否放在 catkin_ws/src 下。
package.xml 是否存在。
是否执行过 catkin_make。
是否 source 了正确的 devel/setup.bash。

查看当前 ROS 包路径：

1	echo $ROS_PACKAGE_PATH

其中应该包含当前工作空间的 src 路径。

CMakeLists.txt 依赖配置

C++ 节点编译失败时，先检查 find_package：

find_package(catkin REQUIRED COMPONENTS
  roscpp
  std_msgs
)

再检查 include 和链接：

catkin_package()

include_directories(
  ${catkin_INCLUDE_DIRS}
)

add_executable(talker src/talker.cpp)
target_link_libraries(talker ${catkin_LIBRARIES})

如果使用自定义消息，还需要添加消息依赖。

package.xml 依赖配置

package.xml 中需要声明构建和运行依赖：

<build_depend>roscpp</build_depend>
<build_depend>std_msgs</build_depend>
<exec_depend>roscpp</exec_depend>
<exec_depend>std_msgs</exec_depend>

依赖缺失时，可能本机因为环境已有包而暂时能编译，但换一台机器就失败。包依赖应该写完整。

自定义 msg 未生成

如果定义了 msg/Person.msg：

1 2	string name int32 age

CMakeLists.txt 需要包含：

find_package(catkin REQUIRED COMPONENTS
  roscpp
  rospy
  std_msgs
  message_generation
)

add_message_files(
  FILES
  Person.msg
)

generate_messages(
  DEPENDENCIES
  std_msgs
)

catkin_package(
  CATKIN_DEPENDS message_runtime std_msgs
)

package.xml 需要：

1 2	<build_depend>message_generation</build_depend> <exec_depend>message_runtime</exec_depend>

编译后重新 source：

1 2	catkin_make source devel/setup.bash

查看消息：

1	rosmsg show demo_pkg/Person

如果忘记 source，Python 或 C++ 代码可能找不到生成的消息类型。

Python 节点不能运行

Python 脚本需要执行权限：

1	chmod +x scripts/talker.py

脚本第一行建议写：

1	#!/usr/bin/env python3

launch 或 rosrun 运行：

1	rosrun demo_pkg talker.py

如果提示找不到可执行文件，检查脚本是否位于包目录下，是否有执行权限，文件名是否和命令一致。

在 CMakeLists.txt 中也可以安装 Python 脚本：

catkin_install_python(PROGRAMS
  scripts/talker.py
  DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
)

清理编译缓存

有时修改依赖或消息后，增量编译状态混乱，可以清理：

cd ~/catkin_ws
rm -rf build devel
catkin_make
source devel/setup.bash

删除 build 和 devel 是常见排查手段，但不要误删 src。

如果多个工作空间叠加，注意 source 顺序。后 source 的工作空间会覆盖前面的同名包。

查看详细编译错误

catkin_make 输出较长时，可以保存日志：

1	catkin_make 2>&1 \| tee build.log

优先看第一处 error，而不是最后一屏。后面的错误可能都是前一个错误引起的连锁反应。

C++ 编译错误常见原因：

头文件路径错误。
命名空间写错。
CMake 没有链接 ${catkin_LIBRARIES}。
自定义消息没有添加生成依赖。

小结

排查 catkin 工作空间问题时，先确认包结构、source 环境和 ROS_PACKAGE_PATH，再检查 CMakeLists.txt、package.xml 和自定义消息配置。Python 节点重点看执行权限和 shebang，C++ 节点重点看依赖、include 和链接。遇到缓存问题可以清理 build、devel 后重新编译。