Windows 源码安装

警告：当前对 Windows 的支持仍处于实验阶段。

Windows 10 或 11 源码安装

Windows 上已支持 OGRE2 渲染功能，Gazebo GUI 也能基本正常工作。这些功能分别对应当前正在构建的 gz-rendering 和 gz-sim 包。在正常使用场景下，这两个包都能构建成功。

注意：可以使用 ogre 作为渲染引擎，而非默认的 ogre2，只需在命令行中追加 --render-engine ogre。

依赖分发（conda-forge）与包管理器（Pixi）

Gazebo 使用的所有依赖的二进制文件均可在 conda-forge 包仓库中找到。Gazebo 的构建农场（buildfarm）和本说明均使用 Pixi 包管理器，不过其他 Conda 包管理器（如 miniforge、mamba 等）应该也可以工作。

安装依赖

1. 如果系统上没有安装用于管理 conda-forge 依赖的包管理器，推荐按照 pixi.sh/latest 上的说明安装 pixi。 安装完成后，关闭终端会话并重新打开，以确保 pixi 已加入 PATH。

2. 安装 Visual Studio 2019 或 2022。 Community 版本对学生、开源开发者和个人开发免费。在“工作负载”（Workloads）选项卡中勾选“使用 C++ 的桌面开发”（Desktop development with C++），勾选“MFC 和 ATL 支持”（MFC and ATL support），并取消勾选“C++ CMake Tools”。我们将通过 Conda 安装 cmake。其余复选框保持不勾选即可。

3. 打开一个 Visual Studio 命令提示符（在 Windows 按钮附近的搜索框中搜索 “x64 Native Tools Command Prompt for VS”）或适用于 VS 的开发者 PowerShell（Developer PowerShell，搜索 “developer powershell”）。可选：右键单击并固定到任务栏，方便以后快速访问。

4. 创建 Pixi 项目目录并下载配置文件。 Pixi 项目会在指定目录内运行，你可以把它创建在系统的任意位置。需要下载两个配置文件：

   mkdir gazebo
   cd gazebo
   curl.exe -L -O https://raw.githubusercontent.com/gazebo-tooling/release-tools/refs/heads/master/conda/envs/noble_like/pixi.toml
   curl.exe -L -O https://raw.githubusercontent.com/gazebo-tooling/release-tools/refs/heads/master/conda/envs/noble_like/pixi.lock

5. 使用 Pixi 安装依赖并启用 Pixi 环境： 进入 Pixi 项目目录（例如 gazebo）后，Pixi 即可安装配置文件中的依赖：

   :: inside the gazebo directory
   pixi install

   安装完成后，Pixi 会提供一个 shell 环境，让所有已安装的库和依赖都可用：

   :: inside the gazebo directory
   pixi shell

   Pixi shell 环境激活后（终端提示符前会出现 (gazebo) 标签），就可以在文件系统的任何位置访问 Pixi 环境。

6. 进入你想存放构建结果的目录，创建并进入工作区目录，然后创建 src 目录来存放 Gazebo 源代码。

   mkdir gz-ws
   cd gz-ws
   mkdir src

7. 然后克隆各仓库：

   vcs import --input https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-jetty.yaml src/

构建 Gazebo 库

Note

请确保你处于 Visual Studio 开发者 shell（上面第 3 步）中，并且已经执行了 pixi shell（上面第 5 步）。

编译器和所有源码就位后，就可以开始编译了。首先进入工作区并列出 colcon 识别到的包：

colcon graph

colcon graph 应以 依赖关系图 的形式列出 Gazebo 库。如果是这样，就可以构建整套库了：

colcon build --cmake-args -DBUILD_TESTING=OFF -DSKIP_SWIG=ON --merge-install --packages-up-to gz-sim gz-tools2

测试被关闭，因为目前 Windows 上不支持测试。

要构建某个包及其所有依赖包：

colcon build --merge-install --packages-up-to PACKAGE_NAME

要构建单个包：

colcon build --packages-select PACKAGE_NAME

更多 colcon 构建和测试选项，请参阅 colcon 文档。

如果没有错误，所有二进制文件就都可以使用了。

使用工作区

每次打开新终端时都需要 source 工作区（并且要先激活 Pixi 环境）。

在新终端中使用已构建工作区的完整步骤是：

# CMD
cd gazebo
pixi shell
call gz-ws\install\setup.bat

# PowerShell
cd gazebo
pixi shell
.\gz-ws\install\setup.ps1

现在你应该可以正常启动 gazebo 了：

gz sim --verbose

或者，在两个不同的终端中分别启动服务器和客户端（两个终端都要 source 安装脚本、pixi shell 和 QT 环境变量）：

# Launch server in one terminal
gz sim -s

# In separate terminal, launch gui
gz sim -g

源码安装说明到此结束；返回 入门 页面，开始使用 Gazebo！

注意 如果你的用户名包含空格（这在 Windows 上很常见），你可能会遇到错误：Invalid partition name [Computer:My User With Spaces]。解决办法是把 GZ_PARTITION 改成其他值：

set GZ_PARTITION=test

记住要在所有其他控制台中设置相同的分区。

卸载源码安装

源码安装可以通过多种方法“卸载”，取决于你想要的结果：

1. 如果你按照上面的说明用 colcon 安装了工作区，所谓“卸载”可能只需要打开一个新终端、不 source 工作区的 setup.bat。这样，你的环境就会表现得像系统上没有安装 Gazebo 一样。

2. 如果你不仅不想使用这些库，还想释放空间，可以从你的 conda 环境中删除整个工作区目录：

   rmdir /s /q <workspace_name>  # gz-ws was used as workspace_name in this document

3. 如果你想保留源代码，可以按需删除 install / build / log 目录，保留 src 目录。

4. 最后，如果你不再需要 Pixi 环境，可以用以下命令删除它：

   rmdir /s /q <pixi_env_path>  # "gazebo" was used as pixi_env_path in this document

故障排除

参见 故障排除