# ROS2 设置教程

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

[ROS2](https://docs.ros.org/en/lyrical/index.html) 是 ROS（机器人操作系统）的最新版本，它是一组为机器人应用设计的库和工具。

本教程介绍如何使用 CLion 作为 IDE 来开发使用 [colcon](https://colcon.readthedocs.io/en/released/) 构建的 ROS2 应用程序。 如果您正在使用较旧的 ROS 发行版，该版本使用  catkin  构建工具，请参考 [之前的教程](ros-setup-tutorial.html)。

以下说明展示了在 Windows 上的以下操作：创建 ROS2 工作区，将其作为编译数据库项目在 CLion 中打开，构建、运行/调试包，添加另一个包以及重建工作区。

Procedure: 准备 ROS2 环境

1. 在您的系统上 [安装](https://docs.ros.org/en/foxy/Installation.html) ROS2。

2. 确保 [source](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files) ROS2 安装成功。 如果遇到问题，请参考同一指南中的提示。

Procedure: 创建工作空间

> **Note:**
> 如果您已经有一个工作区，请跳到 [构建工作区并生成编译数据库](#build-ws)。

我们将以官方的 [简单发布者和订阅者（C++）](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html)指南为例。

1. 以管理员模式打开终端。

2. [Source](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files) ROS2 安装。 在我们的案例中，命令是

```CONSOLE
call C:\dev\ros2\ros2-windows\local_setup.bat
```

> **Tip:**
> 如果您收到  RTI Connext DDS 环境脚本未找到 的警告，您可以在本教程作用域内安全地忽略它。

3. 为新工作区创建一个目录并进入该目录

```CONSOLE
md \dev_ws\src
cd \dev_ws\src

```

4. 创建一个  publisher-subscriber  包

```CONSOLE
ros2 pkg create --build-type ament_cmake cpp_pubsub
```

按照以下 [步骤](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html#tasks)获取源文件，  `CMakeLists.txt`  和  `package.xml` ，直到构建为止。

此时，我们有以下文件夹结构：

```CONSOLE
|_dev_ws
   |_src
      |_cpp_pubsub
         |_include
         |_src
               subscriber_member_function.cpp
               publisher_member_function.cpp
           CMakeLists.txt
           package.xml

```

Procedure: 在终端中构建工作区并生成编译数据库

为了能够在 CLion 中打开 ROS2 工作区，我们将使用 [JSON 编译数据库](https://www.jetbrains.com/zh-cn/help/clion/compilation-database.html)，并通过 [CMAKE_EXPORT_COMPILE_COMMANDS](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html) CMake 标志生成它。

此选项仅在 CMake 的 Makefile 和 Ninja 生成器中受支持，因此我们还需要使用  `-G` 在生成器之间切换。

1. 在最初 source ROS2 安装的同一终端中，导航到工作区级别的文件夹（在我们的案例中为  `dev_ws` ）并运行

```CONSOLE
colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja
```

> **Tip:**
> 如果您收到  生成器：执行 make 失败 错误，请尝试在构建前初始化 Visual C++ 环境。 根据需要自定义以下命令中的路径：
>
> `call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64`
>
> 然后再次运行构建命令。

2. 构建完成后，请确保  `dev_ws\构建` 包含一个  `compile_commands.json` 文件。 如果文件不存在，请确保您的  colcon 版本支持生成工作区级别的编译数据库（请参阅此 [问题](https://github.com/colcon/colcon-cmake/issues/61)）。

Procedure: 在已 source 的环境中启动 CLion

1. 在同一终端中，source 工作区的设置文件：

```CONSOLE
call install/setup.bat
```

2. 接下来，从同一个 shell 启动 CLion。 有关更多信息，请参阅 [命令行界面](working-with-the-ide-features-from-command-line.html)。

例如，在使用 Toolbox 的情况下，您可以创建一个 [启动 IDE 的脚本](https://www.jetbrains.com/zh-cn/help/clion/working-with-the-ide-features-from-command-line.html#generate-shell-scripts)。 在我们的案例中，它位于  `C:\IDE_shell_scripts` 。

```CONSOLE
cd C:\IDE_shell_scripts\
clion

```

3. 结果是，CLion 将在已准备好的 ROS2 环境中启动。

Procedure: 在 CLion 中打开工作区

1. 在 CLion 中，从主菜单调用  `文件 | 打开` 并选择顶级  `构建` 目录中的  `compile_commands.json` 文件：

![将 ROS2 工作区作为编译数据库项目打开](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_compdb_open.png)

2. 点击   作为项目打开  ：

![将 compDB 作为项目打开](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_compdb_open_as_prj.png)

3. 检查项目是否成功加载：

![ROS2 工作区的初始加载](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_load_initial.png)

Procedure: 更改项目根目录

默认情况下，CLion 将包含  `compile_commands.json` 文件的目录视为项目根目录。 在我们的案例中，它是  `构建` 目录。 在项目树中，实际的源文件被标记为外部文件：

![源文件标记为外部文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_external_sources.png)

为了获得正确的项目结构，我们需要将项目根目录设置为实际的工作区目录。

1. 从主菜单调用  `工具 | 编译数据库 | 更改项目根目录` 并选择工作区目录（在我们的案例中为  `dev_ws` ）。

2. 检查项目视图中的更改：

![工作区项目根目录](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_change_prj_dir.png)

此时，所有 CLion 的 [编辑功能](working-with-source-code.html)都完全可用于工作区的源代码。

> **Tip:**
> 默认情况下，CLion 不会在  `compile_command.json` 发生更改时自动重新加载项目，除非是 VCS 更新等外部事件。 您可以在  `设置 | 构建、执行、部署 | 构建工具` 中更改此行为。
>
>
>
> 请参阅 [编译数据库：配置自动重新加载](compilation-database.html#compdb_reload)。

## 如何构建包

为了在 CLion 中构建并启动包，我们将为  `colcon build` 期间实际执行的 CMake 命令创建一个 [自定义构建目标](custom-build-targets.html#customtarget-compdb)，然后为该目标创建一个 [自定义应用程序配置](custom-build-targets.html#custom-rundebug)。

Procedure: 1. 为 'colcon 构建' 命令创建脚本

1. 导航到构建日志目录。 在我们的案例中，它是  `C:\dev_ws\log\latest_构建\cpp_pubsub` 。 打开最新构建的  `command.txt` 文件。

2. 将命令复制到另一个文件中并将其修改为以下内容：

```BASH
"C:\Program Files\CMake\bin\cmake.EXE" C:\dev_ws\src\cpp_pubsub -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja -DCMAKE_INSTALL_PREFIX=C:\dev_ws\install\cpp_pubsub
"C:\Program Files\CMake\bin\cmake.EXE" --build C:\dev_ws\build\cpp_pubsub -- -j8 -l8
"C:\Program Files\CMake\bin\cmake.EXE" --install C:\dev_ws\build\cpp_pubsub

```

> **Tip:**
> 此脚本将从包的构建目录  `构建/cpp_pubsub` 中调用，并在那里生成编译数据库文件。 为了保持一致性，您可以通过在末尾添加以下命令将该文件复制到工作区  `构建` 级别。
>
>
>
>
> ```BASH
> copy  C:\dev_ws\build\cpp_pubsub\compile_commands.json  C:\dev_ws\build
> ```

3. 将文件保存为  `.bat` 脚本。 在我们的示例中，它被称为  `cmake_commands.bat` 并放置在  `c:\dev_ws\src\cpp_pubsub\` 中。

Procedure: 2. 创建自定义构建目标

1. 在 CLion 中，转到  `设置 | 构建、执行、部署 | 自定义构建目标` 并点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)以添加新目标。

2. * 将 工具链 设置为 Visual Studio。 有关在 CLion 中配置 Visual Studio 工具链的更多信息，请参阅 [Windows 教程](https://www.jetbrains.com/zh-cn/help/clion/quick-tutorial-on-configuring-clion-on-windows.html#MSVC)。

* 点击 构建 字段旁边的三点图标。 然后点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)以添加外部项。 在 程序 字段中，选择新创建的脚本。 将 工作目录 设置为包的构建目录。

![为 CMake 命令创建自定义构建目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_customtool.png)

3. 保存自定义目标。

Procedure: 3. 为自定义构建目标创建运行/调试配置

为了能够构建并启动我们为包创建的目标，我们需要创建一个相应的 [配置](run-debug-configuration.html)。

1. 在主菜单中，转到  `运行 | 编辑配置` ，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)并选择   自定义构建应用程序  。

2. 在配置设置中，选择   目标  并确保从   启动前  区域中移除   构建  。

![自定义配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_custom_config.png)

Procedure: 4. 构建包

1. 在工具栏切换器中选择配置：

![构建配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_config_switcher.png)

2. 点击锤子图标或按  `Ctrl + F9` 。 或者，从主菜单调用   构建 | 构建 '构建 cpp_pubsub'  。

3. 在运行工具窗口中检查结果。

> **Tip:**
> 如果您在包中添加或删除了文件，编译数据库将相应地重新生成。 请确保重新加载它或 [配置自动重新加载](compilation-database.html#compdb_reload)。

Procedure: 运行/调试包

1. 再次打开   编辑配置  对话框。

2. 将 [构建配置](#custom-apps)修改为以下内容：

* 将 可执行文件 设置为实际的包二进制文件。

* 请选择 以管理员权限运行 复选框。 有关更多信息，请参阅 [以 root 身份调试](debug-as-root.html)。

![包的运行/调试配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_run_talker_config.png)

3. 保存配置后，它已准备好   运行   ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.execute.svg)或   已调试   ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.startDebugger.svg)。 所有 CLion 的 [调试](debugging-code.html)和 [动态分析](profiling-tools.html)功能都将可用于工作区代码。

CLion 将从目标的工具链中获取调试器。 在我们的案例中，它是 [MSVC LLDB](quick-tutorial-on-configuring-clion-on-windows.html#msvc-debugger)。

> **Tip:**
> 调试的另一种选择是，在 CLion 外部启动一个包，然后 [附加调试器](attach-to-process.html)到正在运行的进程。

## 如何构建工作区

现在让我们看看如何在 CLion 中添加一个新包并重建整个工作区。 为了说明这一点，我们将以向  `dev_ws` 工作区添加一个 [简单服务和客户端](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Service-And-Client.html)包为例。

Procedure: 准备新包文件

1. 在终端中， [source](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files) ROS2 安装并导航到  `dev_ws\src` 。

2. 创建一个新包

```CONSOLE
ros2 pkg create --build-type ament_cmake cpp_srvcli --dependencies rclcpp example_interfaces

```

3. 按照 [步骤](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Service-And-Client.html#tasks)获取源文件，  `CMakeLists.txt`  和  `package.xml` ，直到构建为止。

Procedure: 构建整个工作区

为了（重新）构建整个工作区，我们将在  `colcon build` 中配置一个 [外部工具](configuring-third-party-tools.html)，并在不离开 CLion 的情况下调用它。

1. 转到  `设置 | 工具 | 外部工具` 并点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)以添加新工具。

2. 将工具配置为执行与我们从命令行构建时使用的  `colcon build` 命令相同的操作：

![用于 colcon 构建 的外部工具](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_colcon_build_external_tool.png)

> **Note:**
> 确保设置   工作目录  。

3. 保存工具后，通过主菜单中的  `工具 | 外部工具` 调用它。

4. 在运行工具窗口中检查结果：

![使用外部工具进行 colcon 构建 的结果](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_colcon_build_results.png)

> **Tip:**
> 下次在运行工具窗口中使用 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.execute.svg)按钮再次重建工作区。

5. 检查  `compile_commands.json` 是否已重新生成并现在包含两个包的实体：

![工作区重建后重新生成的编译数据库](https://resources.jetbrains.com/help/img/idea/2026.3/cl_ros2_compdb_regenerated.png)

6. 确保重新加载编译数据库（按 `Ctrl+Shift+O` (Windows), `⌘ ⇧ I` (macOS), `⌘ ⇧ O` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ I` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `⌘ ⇧ I` (Sublime Text (macOS)), `⌘ ⇧ I` (Xcode), `Ctrl+Shift+O` (Visual Studio), `⌘ ⇧ I` (Visual Studio (macOS)), `Ctrl+Shift+O` (ReSharper), `⌘ ⇧ I` (ReSharper (macOS)), `Ctrl+Shift+O` (QtCreator), `Ctrl+Shift+O` (QtCreator (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS))或从主菜单调用  `工具 | 编译数据库 | 重新加载编译数据库项目` ）。 为了避免手动重新加载项目， [配置自动重新加载](compilation-database.html#compdb_reload)。

此时，两个包都已包含在 CLion 项目模型中，您可以像往常一样使用它们。 要构建并运行第二个包，请按照 [上述](#build-pkg)描述的步骤操作。

## See also

### 快速开始

[教程：在 Windows 上配置 CLion](quick-tutorial-on-configuring-clion-on-windows.html) [自定义构建目标和应用程序](custom-build-targets.html) [编译数据库](compilation-database.html)

### 外部链接

[ROS wiki](https://wiki.ros.org/)

