VSCode + Docker 配置

使用 VSCode 和 Docker 搭建 ROS 2 开发环境（社区贡献）

安装 VS Code 和 Docker

借助 Visual Studio Code 和 Docker，无需更换操作系统或安装虚拟机，即可运行所需的 ROS 2 发行版。 本教程将带你搭建一个 Docker 容器，供后续 ROS 2 项目使用。

安装 Docker

安装 Docker 并配置用户权限，执行以下命令。

$ sudo apt install docker.io git python3-pip
$ pip3 install vcstool
$ echo export PATH=$HOME/.local/bin:$PATH >> ~/.bashrc
$ source ~/.bashrc
$ sudo groupadd docker
$ sudo usermod -aG docker $USER
$ newgrp docker

现在运行以下命令验证安装是否成功：

$ docker run hello-world

如果 hello-world 无法直接运行，可能需要先启动 Docker 守护进程：

$ sudo systemctl start docker

安装 VS Code

执行以下命令安装 VS Code：

$ sudo apt update
$ sudo apt install software-properties-common apt-transport-https wget -y
$ wget -q https://packages.microsoft.com/keys/microsoft.asc -O- | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main"
$ sudo apt install code

在终端中输入 code 即可启动 VS Code。

安装 Remote Development 扩展

在 VS Code 的扩展面板（Ctrl+Shift+X）中搜索「Remote Development」并安装。

在 Docker 和 VS Code 中配置工作空间

添加你的 ROS 2 工作空间

创建一个工作空间，用于后续在容器中构建并打开，例如：

$ cd ~/
$ mkdir ws
$ cd ws
$ mkdir src

现在在工作空间根目录下创建一个 .devcontainer 文件夹，并在其中添加 devcontainer.json 和 Dockerfile。 工作空间结构应如下所示：

ws
├── .devcontainer
│   ├── devcontainer.json
│   └── Dockerfile
├── src
    ├── package1
    └── package2

然后在 VS Code 中，通过 File->Open Folder... 或 Ctrl+K Ctrl+O 打开 ws 工作空间文件夹。

为你的环境编辑 devcontainer.json

Dev Container 要正常工作，需要以正确的用户身份构建镜像。 请在 .devcontainer/devcontainer.json 中添加以下内容：

{
    "name": "ROS 2 Development Container",
    "privileged": true,
    "remoteUser": "YOUR_USERNAME",
    "build": {
        "dockerfile": "Dockerfile",
        "args": {
            "USERNAME": "YOUR_USERNAME"
        }
    },
    "workspaceFolder": "/home/ws",
    "workspaceMount": "source=${localWorkspaceFolder},target=/home/ws,type=bind",
    "customizations": {
        "vscode": {
            "extensions":[
                "ms-vscode.cpptools",
                "ms-vscode.cpptools-themes",
                "twxs.cmake",
                "donjayamanne.python-extension-pack",
                "eamodio.gitlens",
                "ms-iot.vscode-ros"
            ]
        }
    },
    "containerEnv": {
        "DISPLAY": "unix:0",
        "ROS_AUTOMATIC_DISCOVERY_RANGE": "LOCALHOST",
        "ROS_DOMAIN_ID": "42"
    },
    "runArgs": [
        "--net=host",
        "--pid=host",
        "--ipc=host",
        "-e", "DISPLAY=${env:DISPLAY}"
    ],
    "mounts": [
       "source=/tmp/.X11-unix,target=/tmp/.X11-unix,type=bind,consistency=cached",
       "source=/dev/dri,target=/dev/dri,type=bind,consistency=cached"
    ],
    "postCreateCommand": "sudo rosdep update && sudo rosdep install --from-paths src --ignore-src -y && sudo chown -R $(whoami) /home/ws/"
}

使用 Ctrl+F 打开查找替换，搜索 YOUR_USERNAME 并替换为你的 Linux 用户名。 不确定自己的用户名？可以在终端中运行 echo $USER 查看。

编辑 Dockerfile

打开 Dockerfile，添加以下内容：

FROM ros:ROS_DISTRO
ARG USERNAME=USERNAME
ARG USER_UID=1000
ARG USER_GID=$USER_UID

# Delete user if it exists in container (e.g Ubuntu Noble: ubuntu)
RUN if id -u $USER_UID ; then userdel `id -un $USER_UID` ; fi

# Create the user
RUN groupadd --gid $USER_GID $USERNAME \
    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME \
    #
    # [Optional] Add sudo support. Omit if you don't need to install software after connecting.
    && apt-get update \
    && apt-get install -y sudo \
    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
    && chmod 0440 /etc/sudoers.d/$USERNAME
RUN apt-get update && apt-get upgrade -y
RUN apt-get install -y python3-pip
ENV SHELL /bin/bash

# ********************************************************
# * Anything else you want to do like clean up goes here *
# ********************************************************

# [Optional] Set the default user. Omit if you want to keep the default as root.
USER $USERNAME
CMD ["/bin/bash"]

将 ROS_DISTRO 替换为你希望用作基础镜像的 ROS 2 发行版，例如 rolling。

打开并构建开发容器

通过 View->Command Palette... 或 Ctrl+Shift+P 打开命令面板， 搜索并执行 Dev Containers: Reopen in Container。 VS Code 会自动构建开发容器。 构建过程需要一些时间，可以趁机休息一下。

测试容器

要验证容器是否正常工作，在 VS Code 中通过 View->Terminal 或 Ctrl+Shift+ 打开终端（选择New Terminal`），然后执行以下命令：

$ sudo apt install ros-$ROS_DISTRO-rviz2 -y
$ source /opt/ros/$ROS_DISTRO/setup.bash
$ rviz2

注意：RViz 的显示可能会遇到问题。 请先通过 xhost +local:<USERNAME> 授予用户对 X Window 系统的访问权限。 如果窗口仍然无法弹出，检查 echo $DISPLAY 的输出值——若为 1，可执行 echo "export DISPLAY=unix:1" >> /etc/bash.bashrc 修复后重试。 你也可以在 devcontainer.json 中修改 DISPLAY 值，然后重新构建容器。