Windows下用WSL2安装ROS2 Humble完整指南与避坑实录

把ROS2装进Windows这事儿我前后折腾过不下十次。最开始在Win10里跑虚拟机后来试过双系统再后来固定用WSL2。项目组的机器人仿真和控制代码全跑在这条链路上Windows端负责VS Code和浏览器Ubuntu子系统负责ROS2进程稳定用了一年多。这篇文章不是把官方文档翻译一遍而是把我踩过的坑、验证过的命令、以及为什么这样做都写清楚目标是让你在Windows下装出一套能正常开发、能跑仿真、能连真机的ROS2环境。先说结论Windows下装ROS2最稳妥的路线是装WSL2然后在WSL2的Ubuntu 22.04里安装ROS2 Humble。我在下文会拆分到每一步并且把容易卡住的地方单独拿出来讲。如果你已经装到一半卡住了可以跳过前面的环境准备直接翻到对应章节看排查思路。1. 动手前的关键判断安装路线与版本搭配1.1 为什么绕开原生Windows和虚拟机ROS2官方其实提供过Windows原生安装包我也试过。装完之后你会发现两个问题一是很多第三方包、硬件驱动、URDF模型库根本没有Windows版本编译时各种缺失依赖二是ROS2生态里的调试工具、launch脚本、设备节点几乎都以Linux为首要目标平台你用Windows原生环境越深入越觉得自己在跟整个社区逆向而行。所以原生路线只适合快速体验命令行不适合正经做开发。虚拟机路线的问题也很直接。VirtualBox或VMware里跑Ubuntu网络模式默认NAT宿主机和虚拟机之间的端口映射、话题通信、设备透传都要额外配置跑Gazebo仿真时图形性能还打折。更麻烦的是工作流被切断了代码在Windows里改运行在虚拟机里测文件同步和IDE调试来回折腾。虚拟机适合偶尔用一下的场景不适合天天构建、频繁调试的日常开发。WSL2解决了上述大部分问题。它不是虚拟机而是一个轻量级实用工具实现完整Linux内核微软自己维护的系统组件和Windows共享文件系统启动快占用低支持GPU加速。对ROS2开发者来说WSL2基本等价于一台运行在你身边的Ubuntu服务器Http通信、主题订阅、设备挂载都能正常工作。1.2 ROS2版本与Ubuntu版本的对应关系安装之前先确定版本搭配。ROS2并不是一个版本通吃所有Ubuntu每个ROS2发行版对应明确的Ubuntu LTS版本乱配会直接导致依赖冲突。ROS2发行版对应Ubuntu版本支持状态Humble HawksbillUbuntu 22.04 (Jammy)维护中适合新手Iron IrwiniUbuntu 22.04我一般不推荐生命周期太短Jazzy JaliscoUbuntu 24.04 (Noble)较新功能全面RollingUbuntu最新版滚动更新不适合稳定开发我选Humble配Ubuntu 22.04作为教程主线。原因很现实绝大多数ROS2第三方包、教学资料、开源硬件驱动现在都默认Humble如果说你后面想装机器人厂商的SDK他们给的示例大多也按Humble来写。如果你用Ubuntu 24.04和Jazzy命令结构基本一致但个别包的安装源名称不同照着本文操作时需要把humble替换成jazzy。WSL2里装哪个Ubuntu版本取决于你想用ROS2哪个发行版。我的建议是不管网上有多少教程说Ubuntu 24.04更好第一次用ROS2就先按22.04来。生态成熟度和排错资料丰富度才是新手最需要的东西。2. Windows端准备启用WSL2并安装Ubuntu 22.042.1 检查Windows版本和WSL状态WSL2不是一个可选的Linux子系统它依赖Windows的虚拟化功能。开始之前先确认三件事Windows 10版本号在19041以上或者Windows 11任何版本。BIOS/UEFI中开启了虚拟化Intel VT-x或AMD-V。当前用户有管理员权限因为部分命令需要提权执行。打开PowerShell管理员输出版本信息wsl --status wsl --version如果提示WSL 1或者找不到命令先更新WSLwsl --update这里有个容易忽略的细节wsl --update会把WSL内核升级到最新版本很多教程没提这一步导致安装Ubuntu后GUI应用比如rviz2、Gazebo打不开。WSLg图形支持依赖于新版WSL所以这一步不要跳过。2.2 安装Ubuntu 22.04的两种方式方式A从Microsoft Store安装。搜索Ubuntu 22.04.3 LTS点击安装。这种方式会自动注册发行版缺点是安装包已经固定后续版本升级需要手动处理。方式B命令行安装我更推荐这种。回到PowerShell执行wsl --install -d Ubuntu-22.04它会把Ubuntu 22.04下载并安装到默认位置安装完成后系统会提示你创建一个UNIX用户名和密码。注意这个用户名不必和Windows用户名一致密码也不会在每次启动时反复询问只在sudo提权时需要。安装完成后检查一下默认版本wsl -l -v输出中会列出所有发行版和版本号确保NAME列是Ubuntu-22.04且VERSION列是2。如果VERSION是1执行wsl --set-version Ubuntu-22.04 2这一步会把发行版从WSL1迁移到WSL2可能需要一两分钟。2.3 进入Ubuntu后的第一轮系统配置首次进入WSL终端先更新软件源和升级系统sudo apt update sudo apt upgrade -y升级到一半如果出现Unable to lock the administration directory或者Could not get lock /var/lib/dpkg/lock多半是你在另一个终端里开着apt进程。WSL里的Ubuntu和你共用同一个文件系统不能同时跑两个apt。关掉其他终端再执行。然后安装几个基础工具后面用得上sudo apt install -y curl wget git build-essential net-tools sudo apt install -y software-properties-common这里我装了software-properties-common因为后面添加ROS2官方软件源时add-apt-repository命令依赖这个包。配置时区也非常重要。ROS2日志和bag包会打时间戳WSL默认时区往往是UTC会导致日志时间和Windows时间差8小时。执行sudo timedatectl set-timezone Asia/Shanghai如果你不在东八区自己换成对应时区即可。时区不对不会让安装失败但会让你后面调试bag包时非常困惑。3. 在Ubuntu子系统里安装ROS2 Humble的核心步骤3.1 添加ROS2软件源为什么不能用默认源直接装Ubuntu默认源里没有ROS2软件包直接sudo apt install ros-humble-desktop会告诉你找不到软件包。所以必须先添加ROS2官方的apt源并导入签名密钥。先确保系统里有universe仓库sudo add-apt-repository universe sudo apt update然后是导入ROS2 GPG密钥sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg这里有个网络问题需要提前说明。raw.githubusercontent.com在国内访问偶尔不稳定如果你执行后发现文件大小是0字节或下载超时可以改用国内镜像源的密钥导入方式。比如清华镜像站的ROS2源就提供对应的密钥同步你可以访问https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu/找到ros.key下载后同样放到/usr/share/keyrings/目录即可。接着写入软件源文件echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release echo $UBUNTU_CODENAME) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null这行命令看起来长拆开解释就是进入ros2.list文件把ROS2源写入源地址使用当前Ubuntu的代号22.04是jammy作为仓库路径。复制粘贴执行即可不用手动编辑文件。更新一次sudo apt update如果看到http://packages.ros.org/ros2相关条目没有报401或404说明源添加成功。3.2 安装ros-humble-desktop还是ros-humble-baseROS2的apt安装包分好几档ros-humble-base只包含核心通信库和命令行工具体积小适合只跑节点通信。ros-humble-desktop包括base、可视化工具、仿真器、示例程序体积大大约3GB适合学习开发。ros-humble-desktop-fulldesktop加上所有扩展很少用。如果你是第一次装我强烈建议装desktop。它自带rviz2、Gazebo、turtlesim、demo_nodes_cpp等不用额外折腾就能体验完整功能。只装base的话后面为了看一个rviz2界面还得单独补图形库反而麻烦。执行安装sudo apt install -y ros-humble-desktop这一步下载时间较长取决于网络。安装过程中如果报依赖错误优先检查是不是/etc/apt/sources.list.d/下其他第三方源和ROS2源冲突最常见的是某些PPA源覆盖了公共库版本。安装完成之后顺手把开发工具也装上sudo apt install -y ros-dev-tools sudo apt install -y python3-rosdep python3-colcon-common-extensionscolcon是后面编译ROS2功能包的核心工具。没装它你后面在src目录下执行colcon build会直接提示命令找不到。3.3 环境变量、rosdep初始化和.bashrc配置安装完成后ROS2命令需要加载环境变量才能用。可以在当前终端执行source /opt/ros/humble/setup.bash但每次打开终端都手动source太蠢。写入.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc接下来初始化rosdepsudo rosdep init rosdep updaterosdep的作用是自动解析功能包的依赖项。项目代码里package.xml声明的依赖在编译前通过rosdep install --from-paths src --ignore-src -r -y一键安装。不初始化rosdep很多从GitHub拉下来的ROS2项目你没法一键装依赖只能手动排查缺少什么效率极低。有一个坑如果你之前装过ROS1/etc/ros/rosdep/sources.list.d/目录下的旧配置会影响rosdep init报already exists。解决办法是删除旧配置后再initsudo rm -rf /etc/ros/rosdep/sources.list.d/* sudo rosdep init4. 功能验证与第一个例程小海龟是怎么跑起来的4.1 命令行验证rostopic和ros2 node list安装完成后先跑个最简单的验证。开两个WSL终端在Windows终端里点加号或按CtrlShiftD拆分分别输入终端1ros2 run demo_nodes_cpp talker终端2ros2 run demo_nodes_cpp listener如果安装正确talker会持续打印Publishing: Hello World: Nlistener会打印I heard: [Hello World: N]。这证明了ROS2核心通信、DDS中间件、节点发现机制都在正常工作。看到这个结果之后CtrlC停掉它们再验证一下命令行工具ros2 node list ros2 topic list如果ros2命令找不到先检查ls /opt/ros/看看目录下是不是humble。如果目录存在但命令找不到大概率是.bashrc没source成功重新执行source ~/.bashrc。4.2 小海龟模拟器完整跑一遍话题通信流程接下来跑经典的turtlesim这比talker/listener更直观能同时验证图形界面、话题、服务和action。终端1ros2 run turtlesim turtlesim_node正常情况下会弹出一个蓝色背景窗口中间有一只小海龟。如果窗口没弹出来多半是WSLg没有启动。确认方法执行echo $DISPLAY输出应该是:0。如果值为空说明WSLg配置异常执行wsl --shutdown后重新进入Ubuntu。终端2ros2 run turtlesim turtle_teleop_key这个终端会提示Reading from keyboard用方向键控制小海龟移动。移动时终端1的窗口里会实时画出轨迹。这里背后的机制是teleop节点发布/turtle1/cmd_vel话题Twist类型turtlesim订阅这个话题从而更新位置。你可以开终端3验证ros2 topic echo /turtle1/cmd_vel在移动海龟的同时能看到终端3不断刷出线速度和角速度数据。4.3 验证rviz2和colcon是否正常小海龟跑通后再验证两个高频工具。rviz2是ROS2最常用的可视化工具ros2 run rviz2 rviz2能弹出界面就算成功。如果界面卡死常见原因有两个一是WSL版本太旧执行wsl --update二是Windows显卡驱动太老去显卡厂商官网更新驱动这一步对Gazebo和rviz2流畅度影响巨大。colcon验证方式是新建一个测试工作空间mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build刚开始src目录是空的colcon会正常完成并生成build、install、log三个目录。如果这一步报错说明colcon安装有问题重新执行sudo apt install -y python3-colcon-common-extensions。5. 把Windows当成开发宿主代码编辑、GUI共享与文件互通5.1 在VS Code里直接编辑WSL内的代码日常开发中代码存在WSL的文件系统里但用Windows端的VS Code打开更舒服。VS Code官方支持Remote - WSL扩展可以直接连接WSL并向WSL内安装VS Code Server。安装流程很简单Windows端VS Code安装扩展WSLms-vscode-remote.remote-wsl然后在WSL终端里进入项目目录执行code .VS Code会自动在WSL环境里启动一个服务器Windows端的编辑器窗口会连接到它。这样做的好处是终端、调试器、Python解释器、CMake工具链都使用WSL内的版本避免Windows和Linux路径混用导致的编译问题。有一个细节值得注意VS Code打开WSL目录后左下角会显示WSL: Ubuntu-22.04。如果你看到的是WSL: Ubuntu说明连接到了默认发行版。如果你机器上装了多个Ubuntu版本务必确认连接的是你装了ROS2的那个。5.2 WSLg的图形界面机制WSL2支持直接运行Linux GUI程序靠的是WSLg组件。你不用安装X Server、不用设置DISPLAY变量系统会自动把Linux侧的GUI请求转发到Windows桌面。rviz2、Gazebo、rqt这类工具能直接弹窗靠的就是WSLg。如果某些老程序需要X11转发可以手动安装sudo apt install -y x11-apps然后执行xeyes如果能看到两只眼睛说明X11转发链路正常。多数情况下WSLg已经够用不需要额外装VcXsrv或Xming这类第三方工具。WSLg偶尔会遇到窗口缩放模糊的问题特别是高DPI屏幕。解决办法是右键启动的窗口标题栏选择属性在兼容性里勾选替代高DPI缩放行为或者调整Windows缩放比例为125%或150%。5.3 文件系统互访/mnt/c和\\wsl$WSL2把Windows磁盘挂载在/mnt/c、/mnt/d等你Windows分区的挂载点。在Ubuntu终端里访问Windows文件cd /mnt/c/Users/你的用户名/Desktop反过来Windows访问WSL文件系统可以在文件管理器地址栏输入\\wsl$\Ubuntu-22.04\home\用户名这里有个性能相关的建议ROS2的源码和构建目录最好放在WSL自己的文件系统里比如~/ros2_ws不要放在/mnt/c下。原因很实际——跨文件系统读写性能差别很大尤其在colcon build大量小文件编译时放在/mnt/c下会比放在WSL原生目录慢3到5倍。如果你代码编辑器在Windows侧打开的是WSL目录仍然可以直接读写VS Code的Remote模式走的是WSL内部的VFS通道性能不会退化。6. WindowsROS2开发的十大踩坑记录6.1 网络问题导致软件源更新失败在WSL里执行apt update或者rosdep update时如果长时间卡住或报超时优先级最高的排查方向是网络。WSL2的网络走NAT模式和宿主机共享IP但DNS解析逻辑是独立的。测试一下ping archive.ubuntu.com如果域名能解析但ping丢包把DNS改成公共DNS是一个常见办法sudo nano /etc/resolv.conf把nameserver改成8.8.8.8或223.5.5.5然后重新apt update。但需要注意WSL每次重启可能会重置resolv.conf持久化方案是创建/etc/wsl.conf[network] generateResolvConf false然后手动管理resolv.conf。这个操作有一定风险新手不建议乱改只在确实遇到DNS问题再处理。6.2 Windows防火墙把WSL的DDS流量拦了ROS2的节点发现依赖DDS协议默认走UDP多播。在WSL2里ROS2节点和另一台机器上的ROS2节点通信时Windows防火墙可能弹出拦截提示。很多人的第一反应是关闭防火墙这是下策关掉防火墙会带来安全风险。正确做法是允许WSL进程通过防火墙。在PowerShell管理员中执行New-NetFirewallRule -DisplayName WSL2 ROS2 DDS -Direction Inbound -InterfaceAlias vEthernet (WSL) -Action Allow -Protocol UDP如果找不到网卡别名先执行Get-NetAdapter查看WSL虚拟网卡的准确名称再做替换。6.3 USB串口、雷达、开发板连不上WSLWindows下装ROS2最大的痛点之一是WSL2默认不能直接访问USB设备。你的激光雷达、STM32开发板、IMU模块插在Windows上WSL里的ls /dev/ttyUSB0一片空白。解决办法是用usbipd-win工具。在Windows PowerShell管理员执行winget install --interactive --exact dorssel.usbipd-win然后在WSL内安装usbip客户端工具sudo apt install -y linux-tools-genericWindows侧列出设备并绑定usbipd list usbipd bind --busid 5-2WSL侧附加设备sudo usbip attach -r 本机IP -b 5-2附加成功后ls /dev/ttyUSB*能看到设备然后还要给当前用户加dialout组权限否则无法访问串口sudo usermod -aG dialout $USER这个是硬件调试最常见的坑我见过不少人在Windows原生ROS2里卡了好几天其实换个思路用usbipd就能干净解决。6.4 安装多个Ubuntu/ROS2版本时混淆环境一台Windows机器上装多个WSL发行版很常见一个Ubuntu 20.04跑ROS1一个Ubuntu 22.04跑ROS2。这时候最容易出问题的是终端默认进错发行版。wsl命令不带-d参数时会进入默认发行版。检查wsl --set-default Ubuntu-22.04把这台Windows默认发行版设为你的ROS2环境避免每次敲wsl都进错Ubuntu。另一个坑是bashrc里写死了多个版本的source。如果你的机器上有ROS1和ROS2共存比如同时用了Noetic和Humble不要把两个版本的setup.bash都写进同一个.bashrc在项目目录用.env或独立脚本管理环境激活不然运行时动态库冲突会让人怀疑人生。6.5 WSL内存占用过高导致Windows卡顿WSL2默认会占最多50%的物理内存如果你电脑只有16GB内存跑Gazebo仿真时Windows宿主会很卡。可以限制WSL内存占用在用户目录下创建.wslconfig文件[wsl2] memory6GB processors4 swap4GB改完后执行wsl --shutdown再重新进入配置生效。这里建议不要低于4GB否则编译大项目时内存不够会启动swap编译速度会大幅下降。6.6 colcon build时提示找不到ros2命令很多新手在编译自己的功能包时打开一个新终端直接colcon build结果提示找不到colcon。原因很简单.bashrc的环境变量只在登录shell加载VS Code集成终端有时候不重新加载bashrc。解决办法source /opt/ros/humble/setup.bash source ~/ros2_ws/install/setup.bash如果你想偷懒在~/.bashrc末尾加上source /opt/ros/humble/setup.bash source ~/ros2_ws/install/setup.bash但这种写法有隐含坑如果某个功能包编译失败install目录里缺setup.bashbashrc会报错。所以我一般建议别把某个工作空间的setup.bash写死在bashrc里每个终端手动source才是安全习惯。6.7 小海龟窗口能开但Gazebo/rtabmap报显卡错误这是WSL2图形层面的高频问题。症状是启动Gazebo时黑屏或者终端刷出一堆libGL error: failed to load driver: swrast。原因是WSL2对OpenGL 3.3的支持取决于Windows侧显卡驱动。解决办法更新Windows GPU驱动去nvidia官网下载对应型号的最新驱动不要用Windows Update自动安装的。确认WSL内可以调用GPUnvidia-smi如果提示找不到命令说明驱动链路有问题。装个mesa-utils再试sudo apt install -y mesa-utils glxinfo | grep OpenGL version看到OpenGL 3.3或4.x就正常。如果只有1.4或者2.1基本可以确定是驱动问题不是ROS2配置问题。6.8 系统休眠或WSL重启后服务全没了WSL2不是常驻服务Windows重启、休眠唤醒之后ros2 run总是提示找不到master或者节点互相发现不了。这个不是安装错了而是WSL里的进程不随Windows启动。解决思路是写个启动脚本。在Windows任务计划程序里创建任务触发条件设为登录时操作为wsl -d Ubuntu-22.04 -u root --service ssh start或者干脆在Windows启动时执行一个脚本启动WS终端并进入指定目录wsl -d Ubuntu-22.04 --cd ~/ros2_ws如果你用Docker容器跑ROS2那还需要额外配置Docker Desktop的自动启动这里不展开了。6.9 磁盘空间不足导致安装中断ros-humble-desktop安装包很大加上WSL本身的Ubuntu系统总共占用可能超过8GB。WSL2的虚拟磁盘文件ext4.vhdx默认只增不减。即使你删了很多文件宿主机上磁盘占用也不会自动下降。如果你发现Windows磁盘空间吃紧在PowerShell里执行wsl --shutdown diskpart # 在diskpart里选择虚拟磁盘文件然后compact vdisk更简单的方法是直接用wsl --manage Ubuntu-22.04 --set-sparse true把虚拟磁盘切换为稀疏模式让.WSL会自动回收未使用空间。前提是WSL版本较新。6.10 ROS2节点跨机器通信时发现不了对方场景是Windows宿主机上的WSL和另一台Linux机器或另一台Windows的WSL之间要通信。除了防火墙规则还要确保两个环境处于同一网段、多播互通。WSL2的IP地址每次重启会变化这对跨机器通信不友好。对象是两台WSL之间通信可以在Windows上启用netsh interface portproxy做端口转发或者直接把DDS域ID和网络接口固定下来。ROS2提供ROS_DOMAIN_ID环境变量来隔离通信域同一台机器多个节点默认是domain 0通信一般没问题。跨机器则还需要确认ROS_LOCALHOST_ONLY没有被设置为1。echo $ROS_LOCALHOST_ONLY如果输出为1说明节点拒绝了非本机通信执行unset ROS_LOCALHOST_ONLY并建议显式设置export ROS_LOCALHOST_ONLY0 export ROS_DOMAIN_ID0实际调试时用ros2 doctor诊断网络连通性是个好习惯自动检查DDS发现、端口、环境变量等比手动逐项排查快得多。7. 装完之后的日常开发习惯建议安装只是开始真正影响开发和上手速度的是日常习惯。基于这几年的使用体验我建议在WSL里固定这几件事。所有ROS2项目的工作空间统一放在~/ros2_ws/src下。不要和Windows桌面路径混用上面已经说了性能差异。为每个项目单独建分支或目录不要把所有代码堆在同一个src下。用colcon编译时系统会自动生成build和install目录如果源码有改动导致编译异常先删掉build和install再重新编译比反复试错省时间。日志和bag包放在WSL内通过\\wsl$路径在Windows文件管理器查看。bag包录制是ros2 bag record -a默认会记录当前所有话题录制时注意在Windows侧实时预瞄空间别录到一半磁盘满了。还有就是代码编辑器务必配置好Python虚拟环境。ROS2节点如果用Python写系统Python目录的写权限是受限的直接用pip往系统里装包会遇到externally-managed-environment错误。解决办法是建虚拟环境python3 -m venv ~/ros2_ws/.venv source ~/ros2_ws/.venv/bin/activate然后在虚拟环境里安装项目专属依赖。注意ROS2本身的Python包还是在系统路径下虚拟环境只放你自己的第三方依赖两者不冲突。最后说说升级这件事。ROS2 Humble会持续维护工作空间里通过apt update apt upgrade升级基础包是安全的但不要因此频繁升级Ubuntu的大版本。WSL里执行do-release-upgrade有一定风险可能导致ROS2依赖的系统库和现有环境不兼容建议只在确实有需求时操作升级前备份好工作空间和bag数据。如果你已经完成上述所有步骤你的Windows机器现在就是一台具备完整ROS2开发能力的机器了。接下来可以尝试自己建一个Python节点发布一个自定义话题再用rviz2可视化把整个链路跑通。这样装出来的环境应付日常学习和小型机器人项目不会有问题。