ros2环境准备

第 0 章 环境准备

学习目标

• 在 Windows 上安装 Docker Desktop，并确认它能正常运行
• 安装 VcXsrv（X 服务器），让容器里的图形程序显示到 Windows 桌面
• 拉取 ROS 2 Jazzy 官方镜像并启动一个持久化容器
• 在容器里跑通第一个图形程序：turtlesim

整体思路

ROS 2 官方推荐的操作系统是 Ubuntu。在 Windows 上体验 ROS 2 最省心的方式，是用 Docker 跑一个装有 ROS 2 Jazzy 的 Ubuntu 24.04 容器，把宿主机当成"遥控器"：

┌─────────────────────────────────────────────┐
│ Windows 主机                                │
│   Docker Desktop ──→ ROS2 容器（Ubuntu 24.04）│
│   VcXsrv（X 服务器）←── 图形窗口（turtlesim 等）│
└─────────────────────────────────────────────┘

容器的图形界面通过 X11 协议转发到 VcXsrv 显示，代码文件通过卷挂载与宿主机共享。

1. 安装 Docker Desktop

1. 从官网下载 Docker Desktop：https://www.docker.com/products/docker-desktop/
2. 双击安装，保持默认选项（Docker Desktop 会要求启用 WSL2，这是 Windows 上推荐的运行后端）。
3. 安装完成后重启电脑，启动 Docker Desktop，等待状态栏显示为绿色（Engine running）。
4. 打开 PowerShell 验证：

docker --version
docker info

如果 docker 命令找不到，重启一次电脑或重新登录 Windows 即可。

提示：如果安装时没有启用 WSL2，可以在 Docker Desktop 的 Settings → General 中勾选 "Use the WSL 2 based engine" 并 Apply & Restart。

2. 安装 VcXsrv（X 服务器）

ROS 2 容器里的 turtlesim、RViz、Gazebo 都是图形程序。Windows 本身不提供 X11 显示服务，所以需要一个 X 服务器把窗口"翻译"出来。VcXsrv 是最常用的免费选择。

1. 下载并安装 VcXsrv：https://sourceforge.net/projects/vcxsrv/
2. 从开始菜单启动 XLaunch ，按下面的配置一路 Next：
   • Display settings：Multiple windows ，Display number 保持 0
   • Client startup：Start no client
   • Extra settings：勾选 Disable access control（关键！否则容器连不上）
   • 点击 Finish
3. 首次启动时如果 Windows 防火墙弹出提示，允许"专用网络"（Private networks）访问。
4. 之后任务栏会出现一个 X 图标，说明 X 服务器已就绪。建议把它设为开机自启，每次学习前先启动它。

替代方案：如果你更熟悉其他 X 服务器（如 Xming），原理相同，后面章节的 DISPLAY 配置不变。

3. 拉取 ROS 2 Jazzy 镜像

在 PowerShell 中执行（首次下载约 2--3 GB，请耐心等待）：

docker pull osrf/ros:jazzy-desktop-full

osrf/ros 是 Open Robotics 官方镜像仓库，jazzy-desktop-full 这个标签包含 ROS 2 完整桌面版（RViz、turtlesim、仿真工具等），适合学习和开发。

4. 启动容器

在 PowerShell 中执行下面的命令（注意是一条 命令，\ 只是换行符）：

docker run -it --name ros2_learning `
  -e DISPLAY=host.docker.internal:0.0 `
  -e LIBGL_ALWAYS_SOFTWARE=1 `
  -v D:/project/codex/ros2_ws:/root/ros2_ws `
  osrf/ros:jazzy-desktop-full `
  bash

命令参数说明：

参数	作用
-it	以交互方式运行，进入容器终端
--name ros2_learning	给容器起名字，方便以后复用（不加 --rm，这样容器里装的软件不会丢失）
-e DISPLAY=host.docker.internal:0.0	告诉容器把图形窗口发给 Windows 上的 X 服务器（端口 6000，即 Display 0）
-e LIBGL_ALWAYS_SOFTWARE=1	使用软件渲染 OpenGL，解决虚拟机/容器里图形黑屏问题
-v D:/project/codex/ros2_ws:/root/ros2_ws	把宿主机的 ros2_ws 目录挂载到容器内 /root/ros2_ws，两边文件实时同步

执行成功后，命令行提示符会变成类似 root@xxxx:/#，说明你已经进入容器。

以后如何再次进入容器？

容器停止后（输入 exit 或重启电脑），不需要重新 docker run，直接用：

docker start ros2_learning

然后打开一个新的交互式终端：

docker exec -it ros2_learning bash

注意：通过 docker exec 进入的终端不会自动加载 ROS 2 环境，每次先执行 source /opt/ros/jazzy/setup.bash（交互式 docker run 进入的终端通常已经自动配置好，但执行一次也无妨）。

5. 验证环境

在容器内依次执行：

echo $ROS_DISTRO
ros2 --help
python3 --version

如果 echo $ROS_DISTRO 输出 jazzy，说明 ROS 2 环境正常。

再验证图形界面：先安装 turtlesim（桌面版镜像通常已包含，未包含时此命令不会报错）：

sudo apt update
sudo apt install -y ros-jazzy-turtlesim

启动小乌龟：

ros2 run turtlesim turtlesim_node

如果桌面上弹出一个蓝色窗口、中间有一只小乌龟，恭喜，你的环境就绪了！按 Ctrl+C 关掉它。

如果窗口没弹出或报 "cannot open display"，先看本章"常见问题"。

6.（可选）VS Code + Dev Containers

在容器里直接用 vim/nano 编辑代码不太方便。推荐安装 VS Code 的 Dev Containers 扩展，把 VS Code 直接"开"进容器里写代码。

1. 安装 VS Code：https://code.visualstudio.com/
2. 安装扩展 Dev Containers（ms-vscode-remote.remote-containers）。
3. 在项目目录创建 .devcontainer/devcontainer.json（内容如下），然后按 F1 → "Dev Containers: Reopen in Container"。

{
  "name": "ros2_jazzy",
  "image": "osrf/ros:jazzy-desktop-full",
  "runArgs": [
    "-e", "DISPLAY=host.docker.internal:0.0",
    "-e", "LIBGL_ALWAYS_SOFTWARE=1"
  ],
  "workspaceFolder": "/root/ros2_ws",
  "mounts": [
    "source=D:/project/codex/ros2_ws,target=/root/ros2_ws,type=bind"
  ],
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python"]
    }
  }
}

不想用 VS Code 的话，直接在宿主机用任意编辑器编辑挂载目录里的文件，容器内同样能读到。

常见问题

现象	原因与解决办法
cannot open display: host.docker.internal:0.0	VcXsrv 没启动，或没勾选 "Disable access control"；重新用 XLaunch 启动并勾选该项
窗口出现但全黑 / 崩溃	显卡驱动与容器不兼容，确认启动容器时带上了 LIBGL_ALWAYS_SOFTWARE=1
docker: command not found	Docker Desktop 未启动或未安装；启动后重开终端
docker pull 很慢或超时	网络原因；可给 Docker 配置国内镜像加速器（Settings → Docker Engine），或在网络环境较好的时间重试
图形窗口一闪而过	X 服务器防火墙拦截；在 Windows 防火墙中允许 VcXsrv 通过"专用网络"
重新进入容器后命令找不到了	先执行 source /opt/ros/jazzy/setup.bash

练习题

1. 关闭容器后重新启动它，确认 turtlesim 依然能打开（验证容器持久化）。
2. 在宿主机 D:\project\codex\ros2_ws 里新建一个 hello.txt，在容器内执行 cat /root/ros2_ws/hello.txt，验证卷挂载生效。
3. 说出 docker run 与 docker exec 的区别。