企业官网建设流程全解析

不知道有多少初学ROS的朋友，第一次在Ubuntu里敲完roscore，兴奋劲儿还没过，就卡在了“怎么把自己写的代码变成一个ROS包”这一步；还有一批人，看着GitHub上各种炫酷的机器人项目想拿来跑一跑，结果catkin_make一执行，满屏红字直接劝退。

这篇文章就是来解决这两件事的：在Ubuntu下创建一个完全属于自己的ROS功能包，以及把一个从GitHub下载的第三方包变成能在自己环境里编译、运行的包。内容会以ROS1 Noetic + Ubuntu 20.04为默认主线，因为这是目前绝大多数初学者教程采用的组合，同时我会在关键步骤里顺手标出ROS2命令的差异，免得你装了ROS2之后还在用ROS1的老命令四处碰壁。

适合谁看？刚装好ROS但不知道下一步怎么走的新手，已经在src目录里丢了好几个GitHub包但一直编译不过的折腾党，还有想把“看教程”变成“自己动手写一个节点”的实践派。文章里所有操作我都会解释背后的逻辑，不会只丢命令，毕竟ROS的精髓不是背命令，而是理解它为什么这么设计。

1. 动手之前的准备：Ubuntu、ROS版本千万别配错

1.1 版本对应关系：选错版本是新手第一座山

很多新手的第一坑，不是代码写错，而是操作系统和ROS版本压根不匹配。

ROS的官方二进制包只支持特定版本的Ubuntu，不是说你Ubuntu装了ROS就能用。截至我写这篇内容时，最常见的组合大概是这样的：

为什么我反复强调Noetic是初学者首选？因为ROS1的学习资料、开源包、教程都最丰富，而且Noetic是ROS1的“绝唱”，官方支持期覆盖到2025年。国内大量教学代码、机器人大赛方案、厂商SDK，默认都还是基于ROS1写的。如果你用的是Ubuntu 22.04，那就老老实实学ROS2 Humble，不要试图在22.04上源码编译ROS1 Noetic——不是说完全不行，但新手没必要用这种方式给自己加难度。

还有一个很常见的操作：用虚拟机还是双系统。如果你只是在学习阶段，VMware或者VirtualBox装Ubuntu 20.04完全够用，只要给虚拟机分配不低于4GB内存、20GB磁盘就行。跑Gazebo这种重型仿真会有点吃力，但学基本的包管理、节点通信没有任何问题。

1.2 安装与换源：手动装还是用一键脚本

ROS安装本身不复杂，但国内网络环境下容易踩坑。官方给的步骤大致是这样：

1. 设置/etc/apt/sources.list，把ROS的软件源加进去。
2. 添加ROS官方GPG密钥。
3. sudo apt update
4. sudo apt install ros-noetic-desktop-full
5. 初始化rosdep：sudo rosdep init && rosdep update
6. 写入环境变量：echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc && source ~/.bashrc

如果你在安装过程中发现下载速度非常慢，可以把packages.ros.org换成国内镜像源（比如中科大、清华的ROS源）。具体操作不复杂：把ROS的源地址写成镜像站的地址就行，网上教程一搜一大把，我不再重复贴代码。

至于最近很多人在用的“鱼香ROS一键安装脚本”，我也试过，确实方便，它会交互式地让你选择要装什么ROS版本、是否安装桌面完整版，然后自动完成换源、rosdep初始化等步骤。对纯新手来说可以省掉很多手敲命令的时间。但我必须提醒一句：脚本只是把官方流程封装起来了，它不会让ROS从“不懂”变成“懂”。安装过程中如果报错，你依然要学会看终端日志，而不是截图去群里问“这是为什么”。

无论用哪种方式装完之后，都先验证一下：

roscore

如果终端能一直跑着不报错，说明ROS环境基本正常。roscore是ROS1的中心节点管理器，相当于整个ROS系统的“总机”，没有它，各个ROS节点之间无法互相发现。

1.3 rosdep 和 .bashrc：这两个东西不搞清楚，后面天天出问题

很多新手不理解为什么要写source /opt/ros/noetic/setup.bash这行命令。简单说，ROS的可执行文件、库文件分散在系统目录里，靠环境变量告诉系统“这些东西在哪”。你不source，系统就不知道去哪找roscore、rosrun这些命令。

source命令只对当前终端窗口有效，所以要把这句话写进~/.bashrc，这样每次打开新终端都会自动加载。这也是新手最常犯的错：在终端A里source了环境变量，然后打开终端B运行rosrun，提示找不到命令，一脸懵。

rosdep的职责则是“依赖管理”。ROS包之间不是孤立的，一个包可能依赖另一个包、依赖某个系统库、依赖某个第三方工具。rosdep会读取包的package.xml文件，把这些依赖解析成对应的apt包名字然后帮你安装。后面从GitHub下载第三方包时，rosdep几乎是绕不开的工具。

如果你执行sudo rosdep init和rosdep update时一直卡住，多数情况是网络环境原因。解决方案网上常见的有两种：一是换一个网络环境多试几次，二是用国内社区维护的rosdep替代工具（比如rosdepc）。对初学者来说，实在初始化不了也别死磕，可以先手动安装依赖，等后面遇到具体包缺依赖时再逐个apt install，慢慢就能用了。

2. 创建自己的ROS功能包：从命名到文件结构一次说清

2.1 工作空间到底是个什么东西

ROS里的“工作空间”概念，很多新手一开始会被绕晕。其实可以把它理解成一个收纳箱，里面放着你这个机器人项目的所有功能包。

一个标准的catkin工作空间长这样：

catkin_ws/ ├── src/ # 所有功能包的源码都放这里 ├── build/ # 编译过程中生成的中间文件、CMake缓存 └── devel/ # 编译完成后生成的可执行文件、库文件、环境变量脚本

创建并编译一个空白工作空间：

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

执行完catkin_make后会自动生成build和devel目录。这里有一个新手容易忽略的点：devel目录里会生成一个setup.bash，你每次编译完自己包之后都要source devel/setup.bash，告诉系统“我自己的工作空间里有新的东西了”。

ROS2的用户注意，工作空间结构其实类似，但编译工具从catkin_make变成了colcon build，生成目录是build/、install/、log/。命令不一样，但思想是一致的。

2.2 catkin_create_pkg 之后的隐藏逻辑

进入src目录，创建一个自己的包：

cd ~/catkin_ws/src catkin_create_pkg my_first_pkg roscpp rospy std_msgs

这条命令会生成一个名为my_first_pkg的文件夹，里面包含package.xml、CMakeLists.txt、include/my_first_pkg和src目录。命令末尾的三个参数是依赖项：roscpp是C++的ROS客户端库，rospy是Python的ROS客户端库，std_msgs是ROS标准消息类型。

很多新手在这里会犯一个错误：以为创建完包就可以直接写代码编译了，结果发现CMakeLists.txt里一大堆注释不知道改哪里，package.xml也没去看过。这里我先把创建过程说透：

catkin_create_pkg这个工具做的事情，本质上是帮你生成两个核心配置文件的模板：package.xml负责描述“这个包是什么、它依赖谁”，CMakeLists.txt负责描述“这个包怎么编译、编译出什么”。这两个文件是ROS包的灵魂，比你的代码本身还重要。

如果你创建包的时候忘了加某些依赖，后面编译时会报Could not find the required component之类的错。解决办法不用删掉重建，直接编辑package.xml和CMakeLists.txt手动补上就行。

2.3 写一个最小可运行的Publisher节点

既然包创建好了，我直接写一个最简单的发布节点，相当于ROS世界里的“Hello World”。

在src/talker.cpp里写：

#include "ros/ros.h" #include "std_msgs/String.h" #include <sstream> int main(int argc, char **argv) { ros::init(argc, argv, "talker"); ros::NodeHandle n; ros::Publisher chatter_pub = n.advertise<std_msgs::String>("chatter", 1000); ros::Rate loop_rate(10); int count = 0; while (ros::ok()) { std_msgs::String msg; std::stringstream ss; ss << "hello world " << count; msg.data = ss.str(); ROS_INFO("%s", msg.data.c_str()); chatter_pub.publish(msg); ros::spinOnce(); loop_rate.sleep(); ++count; } return 0; }

这段代码的逻辑跟字面意思一样简单：初始化一个叫talker的节点，在话题chatter上以10Hz的频率发布std_msgs::String类型的消息。ros::Rate控制循环频率，spinOnce()让回调函数有机会被触发，loop_rate.sleep()保证循环不会跑得太快。

ROS2里这段代码的差异比较大，要用rclcpp、create_publisher、create_wall_timer这些API，写法完全不同，所以如果你学的是ROS2，先别急着把这段代码硬套进去，最好直接去学ROS2的demo_nodes_cpp例子。

2.4 package.xml和CMakeLists.txt该改哪一行

写完源码，还得让构建系统知道“这个cpp文件要编译成什么”。

在CMakeLists.txt里找到这些关键位置并修改：

find_package(catkin REQUIRED COMPONENTS roscpp rospy std_msgs )

然后往文件末尾加上：

add_executable(talker src/talker.cpp) target_link_libraries(talker ${catkin_LIBRARIES}) add_dependencies(talker ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})

第一条告诉CMake“把src/talker.cpp编译成一个叫talker的可执行文件”，第二条把ROS的库链接进来，第三条处理消息生成顺序。对于只用标准消息的程序，第三条有时可以忽略，但一旦你后续自定义消息，add_dependencies加不加会直接影响编译是否成功，养成习惯直接写上最稳。

然后检查package.xml，确保依赖声明完整：

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

如果你用的是较新的ROS Noetic，package.xml里更推荐用<depend>标签代替build_depend和exec_depend分开写，效果一样，更简洁。

编译并运行：

cd ~/catkin_ws catkin_make source devel/setup.bash

然后打开两个终端，终端1运行roscore，终端2运行：

rosrun my_first_pkg talker

再开一个终端，用rostopic echo /chatter看看，如果能刷出data: hello world 0之类的消息，恭喜，你的第一个ROS包已经真正跑起来了。

3. 从GitHub拿包：下载、放对位置、编译三步走

3.1 先辨认一个GitHub仓库是不是ROS功能包

自己在GitHub上找包，第一件事不是git clone，而是先判断这个仓库的结构。ROS功能包的判定标准非常简单：看根目录下有没有package.xml和CMakeLists.txt。

但现实情况更复杂，有的仓库本身就是一个功能包，有的则是多个功能包的集合（叫metapackage或者直接一个repo塞好几个包）。举个例子，一个激光雷达的驱动仓库，结构可能是这样：

lidar_ros/ ├── package.xml ├── CMakeLists.txt ├── src/ └── launch/

这种本身就是一个包，clone下来之后直接放到~/catkin_ws/src/下面就行。

也可能长这样：

robot_arm/ ├── arm_bringup/ # 里面有package.xml，是一个包 ├── arm_description/ # 也是一个包 ├── arm_moveit_config/ # 还是包 └── README.md

这种repo下有多个子目录，每个子目录里面才有package.xml。同样直接整个clone到src目录下，catkin会自动递归扫描所有子目录，找到所有功能包。

新手最常踩的坑是用GitHub网页上的“Download ZIP”下载，解压之后得到的是一个带-main后缀的文件夹。比如你下载了my_package-main.zip，解压后是my_package-main/，直接把它丢进src后会出现一个问题：包内部package.xml里写的包名可能是my_package，文件夹名也是my_package才能保证rosrun按包名找到。所以解压后最好把文件夹重命名成包名：

mv my_package-main my_package

3.2 编译第三方包前先做依赖体检

从GitHub下载的包，90%的情况下直接catkin_make是会报错的，原因不是代码有问题，而是你的系统里缺了它需要的依赖库。

正确的操作顺序应该是：

第一步，打开仓库的README，看作者有没有写“依赖项”和“编译测试”部分。很多国内作者会直接列出依赖的apt命令和启动方式，这能省你大量时间。

第二步，用rosdep自动安装依赖：

cd ~/catkin_ws rosdep install --from-paths src --ignore-src -r -y

--from-paths src表示检查src目录下所有包，--ignore-src表示只通过apt安装，不编译源码，-y表示过程中询问全部选yes。执行完后它会自动把所有ROS依赖安装好。

第三步，如果包里用到了系统级的库（比如Eigen、OpenCV、serial这类），rosdep有时候管不到，需要你自己手动装：

sudo apt install libeigen3-dev libopencv-dev

怎么知道缺什么？不用猜，编译时会报错。比如编译提示Could not find a package configuration file provided by "serial"，那就说明缺serial库。这时可以试试：

apt-cache search ros-noetic-serial

只要能看到带ros-noetic-前缀的包，直接用sudo apt install装就行。这个用apt-cache search找包名的方法，是排查依赖时最实用的技能，比抱着报错去搜索引擎要快得多。

3.3 GitHub访问不畅时怎么办（合规可用的三个替代方案）

我知道很多人卡在“不是不想用GitHub，是clone到一半就断了”。这确实是个很现实的问题，毕竟一个仓库动辄几百MB，网络一抖就前功尽弃。

我试下来最有效的三个方案，全部是公开且合规的：

方案一，直接在GitHub仓库页面点击Code -> Download ZIP下载压缩包。这个方法不需要git命令，不会出现git clone中途断掉的情况，下载完了解压到src目录就能当作一个包来编译。

方案二，用国内代码托管平台的“导入仓库”功能。很多代码托管平台（比如Gitee）都支持直接从GitHub导入公开仓库，导入之后你再从国内服务器clone，速度会快很多。这种方式不会影响原仓库，而且你可以在自己的导入仓库里随时拉取更新。

方案三，如果你只是想先看看包里的代码长什么样，不急着下载，也可以直接用支持GitHub的网页镜像站点浏览文件。但真正要用的时候，我依然推荐方案一和方案二，完整、干净、不易出错。

我不推荐任何需要额外安装客户端或所谓“加速工具”的方法，那些东西安全性和稳定性都不可控，而且完全没有必要。

3.4 一个典型的第三方包编译完整流程演示

我拿一个常见场景演示一遍：假设我从GitHub上下载了一个小车底盘驱动包，放到本地后开始操作。

cd ~/catkin_ws/src git clone https://github.com/example/chassis_driver.git # 或者是下载zip后解压并重命名 cd ~/catkin_ws rosdep install --from-paths src --ignore-src -r -y catkin_make

如果一切顺利，你会看到结尾出现类似[ 100%] Built target chassis_driver_node的信息。然后source环境变量：

source devel/setup.bash

启动方式作者一般会写在README里，可能是：

roslaunch chassis_driver chassis_driver.launch

也可能是：

rosrun chassis_driver chassis_driver_node

注意roslaunch和rosrun的区别：rosrun直接运行一个节点，roslaunch则会读取launch文件，一次性帮你启动多个节点和参数配置。实际项目中几乎全是用roslaunch，因为一个机器人系统动辄十几个节点，不可能一个终端一个终端地敲rosrun。

4. 编译第三方包报错定位：最常遇到的几个坑和我的排查思路

4.1 “Could not find a package configuration file provided by xxx”

这是第三方包编译时出现频率最高的一类报错。

报错原文类似：

CMake Error at CMakeLists.txt:30 (find_package): Could not find a package configuration file provided by "move_base" with any of the following names: move_baseConfig.cmake move_base-config.cmake

翻译成人话：CMakeLists.txt里要求系统提供move_base这个包，但系统里没找到。解决办法很简单：

sudo apt install ros-noetic-move-base

问题是怎么知道apt包名？规律几乎都是ros-<版本名>-<依赖名>，你把报错里的名字换成小写、加横线就行。比如navigation包对应ros-noetic-navigation，gmapping对应ros-noetic-gmapping。

我自己的排查固定套路是这样：

1. 先用apt-cache search ros-noetic-<名字>看看有没有同名包，有就直接装。
2. 如果没有，可能是某个系统库，比如serial、opencv这种，去GitHub仓库的README或者issue里搜一下别人是怎么装的。
3. 如果还找不到，再考虑是不是包本身在ROS2下用的，或者依赖了某个版本很新的库。

4.2 编译成功却提示“package 'xxx' not found”

这个报错不是编译阶段出现的，而是运行阶段。rosrun my_pkg my_node却提示找不到包，最常见的原因是：你忘了source自己工作空间的环境变量。

新手往往编译完就急着运行，结果catkin_make确实成功了，但没有执行：

source ~/catkin_ws/devel/setup.bash

系统的$ROS_PACKAGE_PATH还是只指向/opt/ros/noetic/share，你的包在home目录下，它当然找不到。

另一个可能原因是新开了终端，.bashrc里只写入了ROS系统自带的环境变量，没有写入你自己工作空间的source。解决办法是在.bashrc里加一行：

echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc source ~/.bashrc

加完之后可以用验证一下：

rospack find my_pkg

如果它能输出你的包路径，说明环境变量已经生效。

4.3 Python节点报错：到底是Python2还是Python3

ROS1 Noetic时代有一个特殊的历史遗留问题：它原生支持Python3，但网上大量旧教程和旧包是基于Python2写的。

如果你运行一个Python节点时出现：

ModuleNotFoundError: No module named 'rospy'

先别急着装包，检查你当前的Python环境：

python --version which python

在Ubuntu 20.04系统上，python命令默认可能没装，只有python3。而很多旧包脚本第一行写的是#!/usr/bin/env python，系统找不到python命令，就会直接报错或者跑进了别的解释器。

解决办法有二：一是把脚本第一行改成#!/usr/bin/env python3；二是给系统创建一个默认Python3的软链接：

sudo apt install python-is-python3

装完之后python --version就会显示3.x。但我更建议前者，改脚本本身比改系统默认更可控，也不会影响其他项目的环境。

另外，Python ROS包的chmod +x权限也值得注意。你从GitHub下载的脚本文件往往没有可执行权限，运行rosrun时会提示Permission denied。手动加一下：

chmod +x ~/catkin_ws/src/xxx_pkg/scripts/xxx_node.py

4.4 编译到一半被系统杀死或卡死

这通常发生在虚拟机用户身上。catkin_make这类工具默认会调用机器的所有CPU核心并行编译，虚拟机分配的核心本身性能就弱，内存又只有2GB，编译大型包（比如navigation、move_base全家桶）时直接OOM，系统杀进程，表现为终端里突然出现Killed字样。

解决办法：限制并行任务数，同时增大交换空间。

cd ~/catkin_ws catkin_make -j2

-j2表示最多同时编译2个任务，牺牲一点时间，但系统不会崩溃。如果你的机器内存是8GB以上，一般不需要这样。

给虚拟机加交换空间的方法也顺便说一下：

sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

这是给系统临时增加4GB虚拟内存，编译大包时的应急手段，不用的时候可以swapoff /swapfile关掉。

4.5 报错速查表：建议直接截图存下来

我把这一节内容汇总成一张表，后续再遇到类似问题可以先对照排查：

这些报错几乎每个从GitHub装过包的人都见过，认识它们比背一条条命令有用得多。

5. 让第三方包真正跑起来：launch文件、参数和你最容易忽略的细节

5.1 launch文件到底是干什么的

很多新手拿到一个GitHub项目后，喜欢直接用rosrun一个个跑节点，这样有两个问题：一是节点多了以后终端管理混乱，二是很多节点之间需要配置参数、重映射话题名，这些用rosrun做起来非常繁琐。

roslaunch就是来解决这个问题的。一个最简单的launch文件长这样：

<launch> <node name="talker_node" pkg="my_first_pkg" type="talker" output="screen"/> </launch>

这行XML的意思：从my_first_pkg包里，运行名为talker的可执行文件，运行时的节点名字叫talker_node，打印信息直接输出到当前屏幕。

注意pkg、type、name三个属性非常容易混：

• pkg：包名，是package.xml里那个名字。
• type：可执行文件的名字，是CMakeLists里add_executable生成的那个名字。
• name：节点运行时的名字，可以随便改，不影响程序逻辑。

保存成launch/talker.launch，然后运行：

roslaunch my_first_pkg talker.launch

你会发现连roscore都不用单独开了，因为roslaunch会自动检测并启动它。

5.2 拿到一个新包，运行之前先看这三样东西

从GitHub下载的包，不要盲目执行启动命令，我习惯先看三样东西。

第一样，README里的启动说明。作者通常会在README写明：这个包需要什么硬件、有哪些launch文件、每个launch文件对应什么功能。很多新手忽略README，结果把雷达驱动包用在没雷达的机器上，自然跑不起来。

第二样，launch目录里的文件内容。打开一个launch文件，你往往能看到大量这样的配置：

<param name="serial_port" value="/dev/ttyUSB0"/> <remap from="scan" to="/my_scan"/>

param是用来设置参数的，第三方包很多参数都要根据你的实际设备改，比如串口号是/dev/ttyUSB0还是/dev/ttyUSB1，车体宽度是多少，雷达话题名是什么。remap则是节点内部话题和实际使用话题之间做映射用的，可以让不同驱动包发出的不同名字的话题统一起来，这是ROS里非常灵活但初学者最容易忽略的一个机制。

第三样，config目录里的yaml参数文件。很多包的launch文件会从外部加载yaml参数，比如这样：

<rosparam file="$(find xxx_pkg)/config/xxx.yaml" command="load"/>

这种情况下，修改参数的最佳位置是yaml文件，而不是直接改launch文件。搞清楚这个层次关系，你改配置就不会越改越乱。

5.3 想改别人的包，但别把原包改坏了

你在GitHub上下一个包，往往不是原封不动就能用的，总要改一改：改话题名、改参数、甚至加功能。

我的建议是：千万不要直接在clone下来的目录里乱改。原因很简单，后续你想从上游拉更新，git pull会被你本地的修改搞出冲突，而你一开始可能并没有记录自己改了什么。

更推荐的做法是分层处理：

• 优先级最低的改动，直接通过launch文件的param和remap来做，这些改动不碰原包代码。
• 需要改固定参数时，复制一份config目录下的yaml文件，在launch里把rosparam file指向你自己的yaml。
• 需要改算法逻辑时，不要改在vendor目录里，而是拷贝整个包，重命名成一个新包再改。重命名包要注意改三处：文件夹名、package.xml里的<name>、CMakeLists.txt里的project()。养成这个习惯，你的工作空间就不会混乱。

另外，如果你准备把这部分改动长期保存，更正规的流程是先把GitHub仓库fork到自己名下，再clone你自己的fork，改完之后push上去，这样既不污染原仓库，也能在团队协作时用PR把改动反馈给原作者。开源协议的问题这里不展开讲了，但用别人的包之前扫一眼LICENSE，尊重作者的规定，是做开源项目的基本修养。

5.4 运行起来之后，怎么确认它真的在工作

roslaunch执行之后，终端里没有红字不代表系统一切正常。ROS是一个分布式通信系统，节点没崩溃也可能因为话题没对上、帧率不对、消息类型不匹配导致整个链路不通。

我的验证习惯是这样：

先看当前有哪些节点在跑：

rosnode list

再看话题列表：

rostopic list

看某个话题的消息频率和内容：

rostopic hz /scan rostopic echo /chatter

如果你启动的是一个激光雷达驱动包，rostopic hz /scan应该能稳定输出10Hz左右的频率数据；如果你启动的是SLAM建图，rostopic echo /map应该能看到map元数据不断更新。这些“运行期验证”比编译通过重要得多，因为编译只代表代码能被构建出来，不代表节点之间真的通信正常。

我在实际使用中发现一个特别值得养成的习惯：每拿到一个新包，第一件事不是急着catkin_make，而是先跑一遍rosdep install --from-paths src --ignore-src -r -y，再打开README看启动命令，最后才开始编译。这个顺序看着简单，却能帮你省掉至少一半的报错排查时间。ROS生态本身就是站在别人的轮子上前进的，学会正确地“捡轮子”，比什么都自己从零写要重要得多。