Windows 下装 ROS2这件事劝退过不少人。早几年你搜到的教程多半是让你装 Ubuntu 双系统或者开个 VMware 虚拟机折腾小半天才能看到那只小乌龟动起来。我自己从接触 ROS 到现在在 Windows 上试过原生安装、试过 Docker、也试过 Hyper-V最后长期留在工作流里的是 WSL2 这条路。这篇文章就用超详细的步骤把在 Windows 上用 WSL2 装好 ROS2 Humble 和 Jazzy 的完整过程讲清楚环境准备、软件源、安装命令、小乌龟验证、开发工具配置以及我在实操中踩过的坑。如果你刚入坑 ROS2 的新手或者想在 Windows 主力机上搭一套不折腾的机器人开发环境照着这篇走就够了。1. 三种主流安装方案怎么选为什么我最终锁定 WSL2先说结论在 Windows 上跑 ROS2主流就三条路——原生 Windows 安装、WSL2、Docker。绝大多数人直接选 WSL2我自己也是长期用它。下面把另外两条路为什么不够香讲清楚你自然就理解这个选择了。1.1 原生 Windows 安装官方虽支持但生态拖你后腿ROS2 官方文档确实提供 Windows 原生安装用 chocolatey 把依赖一套拉下来Foxy 时代我还真照着文档配成功过一次。但原生方案有几个非常现实的问题。第一软件包生态不完整。很多教学演示包、仿真工具、SLAM 建图包里都有 Linux 专属依赖Windows 下经常要从源码自己编译。编译 ROS2 的 C 包时CMake 动不动就找不到某个 Linux 路径下的库尤其像 Gazebo、Nav2 这种重量级项目在 Windows 上要么缺依赖、要么缺补丁新手遇到基本就是在劝退边缘。第二命令行工具链和 Python 环境容易乱。ROS2 的命令行工具默认在 bash 里体验最好PowerShell 和 cmd 下的转义符、路径分隔符差异能把人逼疯再加上 Windows 上装过 Anaconda、PyTorch 的人python.exe 指向混乱是常事。ROS2 依赖的 Python 环境一乱colcon build 就会爆出一堆跟系统毫无关系的错误。所以我一直跟朋友说除非公司强制要求纯 Windows 环境否则别拿原生安装折磨自己。ROS2 设计时的目标平台是 Linux硬搬到 Windows 上属于逆流而上不是不能跑是后续扩展每一步都难受。1.2 WSL2 与 Docker、虚拟机的横向对比WSL2 本质上是一个跑在 Hyper-V 轻量虚拟机里的完整 Linux 发行版但它和传统虚拟机有个明显区别和 Windows 的文件系统、网络、剪贴板都有深度集成。对 ROS2 来说有完整 Linux 内核就意味着 Gazebo 物理引擎、C 节点编译、串口设备读取、共享内存通信这一整套生态都能直接跑不会出现Windows 下没有某内核模块这种尴尬。Docker 是另一种看起来干净的做法镜像拉下来就能跑环境隔离做得很好。但它更适合部署验证不适合日常开发改代码要做 volume 挂载看窗口要做 X11 转发连 USB 设备要做 device 映射。这一套配置下来比装两遍 ROS2 还费神。传统虚拟机VMware/VirtualBox则占资源明显而且文件共享、网络桥接都要额外设置。维度原生 Windows 安装WSL2 方案Docker 容器生态兼容性差Linux 专属依赖多好完整 Linux 内核好但设备/图形映射麻烦GUI 显示原生窗口WSLg 直接显示需 X11 转发USB/串口设备依赖 Windows 驱动支持较多需要额外映射日常开发体验命令行/Python 环境容易乱接近原生 Linux环境隔离但配置成本高适合场景公司强制要求绝大多数新手和日常开发部署、CI、复现实验日常体验上WSL2 打开一个终端直接敲 wsl 就进入 Ubuntu代码放在 Linux 文件系统里Windows 侧在资源管理器地址栏敲 \wsl$ 就能访问GUI 程序靠着 WSLg 自动弹出窗口rviz2、gazebo、turtlesim 都能正常显示。所以对绝大多数人来说WSL2 就是当前 Windows 下开发 ROS2 的最优选。2. 环境准备把 WSL2 和 Ubuntu 跑起来有了方案接下来就是动手。装 WSL2 本身不难但有三步前置检查能帮你省掉一半的报错我按顺序来。2.1 检查 Windows 版本与虚拟化开关WSL2 的基本门槛是 Windows 10 2004Build 19041及以上或者 Windows 11。Win10 老版本也能手动开启但新特性都是围绕高版本做的能用新系统就别在旧系统上死磕。做三件事按 WinR 输入 winver确认系统版本。进 BIOS/UEFI确认 Intel VT-x 或 AMD-V 已开启。很多人装完 WSL 一直报虚拟化相关错误最后发现就是 BIOS 开关没开。以管理员身份打开 PowerShell执行 wsl --status 看当前 WSL 状态。这三步看起来基础但能拦住一半的报错。特别是 BIOS 虚拟化我遇过的案例里十个有八个是这里没开。有些人笔记本出厂默认安全启动和虚拟化是关着的你进去改成 Enabled 再重启就行。2.2 一条命令安装 WSL2 和对应版本的 Ubuntu如果系统满足版本要求最省事的方式是在管理员 PowerShell 里执行wsl --install它会一次性开启适用于 Linux 的 Windows 子系统和虚拟机平台两个 Windows 功能再下载 WSL2 内核默认装一个最新 Ubuntu 发行版装完让重启就重启。注意这条命令默认安装的 Ubuntu 是 24.04对应的是 ROS2 Jazzy如果你想装 Humble建议指定安装 Ubuntu 22.04wsl --install -d Ubuntu-22.04如果想先看看有哪些发行版执行 wsl --list --online。装好后用 wsl -l -v 确认 VERSION 列是 2如果是 1就执行wsl --set-version Ubuntu-22.04 2这里插一个常见坑微软商店的 Ubuntu 下载经常卡住或报错。这种情况不要跟商店死磕直接用命令行 wsl --install -d Ubuntu-22.04这实际也是从官方渠道拉发行版更稳。2.3 首次启动、Linux 用户名与系统更新第一次启动 WSL 里的 Ubuntu会让你设置 Linux 用户名和密码。注意两件事一是密码输入时屏幕上不会显示任何字符这是正常现象别以为键盘坏了二是用户名建议用小写字母比如 ros后续大量命令都要经过这个家目录。设置完进入 Ubuntu 后先把系统更新一遍sudo apt update sudo apt upgrade -yapt 默认的下载源指向国外官方地址访问速度可能不稳定。如果感觉 update 特别慢可以把 /etc/apt/sources.list 里的地址替换成国内开源镜像源比如清华源、阿里源。这一步不是必须但能明显提升后续 ROS2 源更新时的体验。3. 正式安装 ROS2以 Humble 为主线Jazzy 同理到这里你的 Windows 上已经有一个干净的 Ubuntu 环境了。下面正式装 ROS2。我以 Humble 为主讲Jazzy 只需要把命令里的 humble 全部替换成 jazzy流程一模一样。3.1 设置 locale提前排掉编码坑ROS2 对系统 locale 有要求如果区域编码不对后面启动节点很容易遇到类似这种报错UTF-8 codec cant decode byte 0xff in position 0新装的 Ubuntu 经常默认不是 UTF-8所以先设置好sudo apt install -y locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 export LANGen_US.UTF-8这里解释下为什么非设不可ROS2 的 rclpy、rclcpp 大量依赖 Python 和 C 的 I/O 编码日志、包描述、消息序列化都要借助 locale 输出。不统一轻则日志乱码重则节点直接起不来。宁可一开始花两分钟设置好。3.2 添加软件源与 GPG 密钥先安装下载工具sudo apt install -y curl gnupg lsb-release然后下载 ROS2 的 GPG 密钥到系统 keyring。我平时用清华镜像加速执行sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/rosdistro/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg接着把 ROS2 的 apt 源写入列表echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu/ $(source /etc/os-release echo $UBUNTU_CODENAME) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null这段命令里的 $(source /etc/os-release echo $UBUNTU_CODENAME) 会自动识别当前 Ubuntu 版本代号22.04 是 jammy24.04 是 noble。所以 Humble 和 Jazzy 的源配置可以共用这一条命令非常省事。如果你不想用镜像把域名换成 packages.ros.org/ros2/ubuntu 也可以只是部分地区访问速度不稳定。配置完执行sudo apt update如果 apt 列表里出现了 ros-humble-* 这类包名说明源配置成功了。3.3 安装桌面版 ROS2 与开发工具Humble 的桌面版命令是sudo apt install -y ros-humble-desktop桌面版已经包含 rviz2、turtlesim、demo 节点、rqt 等常用组件适合直接上手。如果你硬盘空间紧张可以用 ros-humble-ros-base 精简版后面用到什么再单独补。Jazzy 就把 humble 全部换成 jazzy。装完核心包后顺手把开发工具链装齐sudo apt install -y python3-colcon-common-extensions ros-dev-tools python3-argcompletecolcon 是 ROS2 的官方构建工具等价于 ROS1 里的 catkin后面自己建工程一定会用到ros-dev-tools 带了 rosdep、vcs 等配套工具argcomplete 是 ROS2 命令行补全的依赖不装的话 Tab 补全基本失效排查问题会很难受。3.4 写入环境变量并验证安装把 ROS2 环境写入 ~/.bashrc这样每次打开终端自动加载不用手动 sourceecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc验证是否装好ros2 --help printenv | grep -i ROS如果看到 ROS_DISTROhumble、ROS_VERSION2恭喜核心环境已经通了。Jazzy 就把路径里的 humble 换成 jazzy其他流程完全一样。4. 实操验证让小乌龟在 Windows 上跑起来环境装好只算成功了一半真正跑起来才安心。这个阶段我用三个小实验验证整个 ROS2 通信链路是否正常。4.1 终端工具准备Windows Terminal装好 ROS2 后强烈建议安装 Windows Terminal。官方商店免费支持多标签页、复制粘贴顺手、中文字体渲染舒服。调 ROS2 节点时我通常开三个标签页一个跑核心节点、一个跑数据处理、一个跑可视化。常用快捷键CtrlShiftT 新开标签页CtrlShiftD 复制当前标签页Alt方向键 切换标签页其中 CtrlShiftD 复制标签页特别实用多个节点需要在同一个工作环境下跑复制出来的标签页直接继承当前目录和 shell 环境。4.2 小乌龟 turtlesim 实测验证 ROS2 是否真的能跑最经典的就是小乌龟。第一个标签页执行ros2 run turtlesim turtlesim_node正常会弹出一个蓝色背景窗口里面趴着一只小乌龟。第二个标签页执行ros2 run turtlesim turtle_teleop_key然后用键盘方向键控制小乌龟移动。移动的同时第一个终端会持续打印小乌龟的位姿变化数据说明话题发布订阅是通的。这一步如果报 command not found: ros2九成是环境变量没加载。回到终端确认 ~/.bashrc 里有没有 source 那一行没有就手动补上再 source。4.3 发布订阅模型验证talker 与 listener小乌龟只验证了话题通信再来验证一下节点间基本的发布订阅。开两个新标签页ros2 run demo_nodes_cpp talker ros2 run demo_nodes_py listenerlistener 会持续打印 talker 发来的 Hello World 字符串。再验证一下节点和话题列表ros2 node list ros2 topic list ros2 topic echo /chatter能看到 /talker、/listener 两个节点在列表里/chatter 话题上有实时流转的消息内容就说明 DDS 发现、话题传输、节点注册这一整套 ROS2 核心通信机制都正常了。后面自己写节点时所有机制都建立在这套发布订阅模型之上。5. 搭建自己的开发空间Colcon 工作流与 VS Code官方 demo 跑通后就要开始写自己的代码了。ROS2 的标准工作空间结构是 src、build、install、log 四个目录这节我把从零创建工程到用 VS Code 开发的完整流程顺一遍。5.1 创建 Colcon 工作空间并完成首次编译创建并编译工作空间mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build第一次 build 会生成 build、install、log 三个目录build 是中间产物install 是最终安装结果log 是编译日志。源码统一放在 src。再创建一个 C 测试包cd ~/ros2_ws/src ros2 pkg create --build-type ament_cmake my_package cd ~/ros2_ws colcon build编译完成后install 目录里会多出 my_package 的环境文件需要把它加入当前 shellsource ~/ros2_ws/install/setup.bash echo source ~/ros2_ws/install/setup.bash ~/.bashrc写入 .bashrc 是为了以后每次开终端自动生效。养成这个习惯后再也不会出现我明明编译了但 ros2 run 找不到包的尴尬。5.2 VS Code WSL 远程开发模式开发 ROS2 最顺手的编辑器我推荐 VS Code。先在 Windows 端安装并加装扩展 Remote - WSL然后在 WSL 终端里执行code ~/ros2_wsVS Code 会自动以 WSL 远程模式打开目录底层其实是在 Linux 侧起了一个 serverWindows 端只是展示界面。这样有两个好处一是终端、编译、运行全部在 Linux 环境里执行不会出现 Windows 端工具链串味二是 C 的 IntelliSense 能正确读取 ROS2 的 CMake 配置文件代码补全和跳转非常准。如果主要写 Python 节点记得在 VS Code 里把解释器选成 /usr/bin/python3Python 扩展会自动识别 ROS2 相关的 Python 包写起来舒服很多。这个组合已经成为我目前最稳定的日常开发姿势。6. 常见问题与避坑指南最后是重头戏。我把自己三年里遇到频率最高的问题全部整理出来按场景分类你遇到哪个查哪个。6.1 WSL 安装与运行类问题wsl --install 报错 0x80070003 一般是系统旧或虚拟机平台服务没启用。检查控制面板里适用于 Linux 的 Windows 子系统和虚拟机平台两个功能是否勾选勾完重启必要时进 BIOS 看虚拟化。wsl -l -v 显示 VERSION 是 1 执行 wsl --set-version Ubuntu-22.04 2 升级。如果卡在转换过程先 wsl --shutdown再重试。大磁盘转换确实慢给点耐心。微软商店下载 Ubuntu 卡死或报错 直接 wsl --install -d Ubuntu-22.04命令行安装更稳别跟商店纠缠。WSL2 占内存太高Windows 侧卡顿 在 C:\Users\你的用户名.wslconfig 里写[wsl2] memory4GB swap4GB保存后执行 wsl --shutdown 重启 WSL 生效。这个配置对 ROS2 完全够用还能保住 Windows 自身性能。系统盘空间被 WSL 的 vhdx 文件撑爆 用 wsl --export 导出发行版到其他盘再 wsl --import 导入到新路径这是把 WSL 挪到别的磁盘的标准玩法建议早点做。6.2 ROS2 安装与使用类问题apt update 后找不到 ros-humble-desktop 包 检查 Ubuntu 版本是否匹配Humble 对应 22.04Jazzy 对应 24.04。再检查 /etc/apt/sources.list.d/ros2.list 是否写对以及 /usr/share/keyrings/ 下密钥文件是否存在。rosdep init 或 rosdep update 失败 新手阶段完全可以跳过 rosdep它主要用于自动解析功能包依赖跑官方示例和自建简单工程根本用不上。等以后做复杂工程再考虑用镜像地址方式解决不要一开始就把时间耗在这里。source 后 printenv | grep -i ROS 无输出 多半是路径写错了。Humble 的路径是 /opt/ros/humble/setup.bashJazzy 是 /opt/ros/jazzy/setup.bash确认没把版本名混掉。同一台 Ubuntu 里装多个 ROS2 发行版 非常不建议。环境变量互相覆盖source 了一个另一个就废了。真想同时用另一个发行版用 Docker 或单独的 WSL 实例。apt 锁文件被占用 执行 ps aux | grep apt 查看是否有 apt/dpkg 进程在跑有就等它结束或者 sudo dpkg --configure -a 修复中断的包管理。6.3 GUI 显示与终端体验类问题rviz2、turtlesim 窗口弹不出来 Windows 11 和较新的 WSL2 默认有 WSLgGUI 可直接显示。窗口不出来就先 wsl --update wsl --shutdown 重启。Windows 10 老版本没有 WSLg可以装 VcXsrv 这个开源 X Server启动后在 WSL 里执行 export DISPLAY:0再运行 GUI 程序。终端一打开就报 bash 错误 大概率是 ~/.bashrc 里的 source 行有问题。用 nano 编辑 ~/.bashrc 检查改完 source ~/.bashrc 验证。Tab 补全不好用 ROS2 命令补全依赖 python3-argcomplete确认已安装。装完后新开一个终端在 ros2 run 后面敲两次 Tab 试试。中文乱码 回到第 3.1 节把 locale 设成 UTF-8同时检查终端字体是否支持中文。最后说点个人体会。我最早在 Windows 上折腾 ROS2 时走的是原生安装路线光环境就重来了三遍chocolatey 依赖和 CMake 编译一个个排查跑通 demo 的成就感没保持多久就被后续装 Gazebo 劝退。后来转到 WSL2感受就四个字一身轻松。直到现在我的主力开发环境还是 Windows 加 WSL2 加 Ubuntu 22.04 加 Humble日常写 Rviz2 插件、跑建图算法都很稳定。如果你照着这篇走到这一步说明你的 Windows 上已经有一台能正常跑 ROS2 的 Linux 开发机了。接下来建议往两个方向深入一是学 rviz2 可视化和 TF 坐标变换二是在自己的工程里用 colcon 管理多包项目。遇到报错时把完整报错原文复制到官方文档和社区搜索不要凭感觉乱改环境变量。以后有机会我再把 WSL2 里接雷达、接 USB 摄像头以及 WSL2 与 Windows 文件系统互访的实战细节整理出来。祝你在 ROS2 的世界里玩得开心。