基于 VS Code 的 Docker 调试环境搭建

本文以 Autoware 项目为例，详细介绍如何在 VS Code 中配置和使用 Docker 容器进行开发调试。

一、Docker 安装与配置

1. 通过官方仓库安装 Docker

按照以下步骤通过官方 APT 仓库安装 Docker 引擎：

# 1. 更新apt包索引
sudo apt update

# 2. 安装必要的依赖包，用于添加HTTPS仓库支持
sudo apt install -y ca-certificates curl gnupg lsb-release

# 3. 添加Docker官方GPG密钥以确保下载安全
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 4. 设置Docker稳定版仓库源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 再次更新apt包索引以包含新添加的仓库
sudo apt update

# 6. 安装Docker引擎及相关组件
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2. 配置免 sudo 权限运行 Docker

默认情况下，执行docker命令需要管理员权限。为提高便利性，可以将当前用户添加到docker用户组中：

# 创建docker用户组（如果尚未创建）
sudo groupadd docker

# 将当前用户添加到docker组
sudo usermod -aG docker $USER

# 应用组更改（无需重新登录）
newgrp docker

验证配置是否成功：

docker run hello-world  # 应该能够无需sudo直接运行

⚠️ 安全提醒：将用户添加到docker组相当于授予其 root 权限，因为 Docker 容器可以访问宿主机的所有资源。请在安全可控的环境中使用此配置。

3. 获取基础镜像

从 GitHub Container Registry 拉取 Autoware 开发环境镜像：

docker pull ghcr.io/autowarefoundation/autoware:universe-devel-20250903-amd64

二、VS Code 开发环境配置

1. 安装必要插件

在 VS Code 扩展市场中搜索并安装Dev Containers插件，该插件提供了容器化开发环境的支持。

2. 创建开发容器配置文件

步骤 1：准备项目目录结构

假设您的工作目录为：

~/work/autoware

在此目录下创建 Dev Container 配置目录：

cd ~/work/autoware
mkdir .devcontainer

步骤 2：配置devcontainer.json文件

Dev Containers插件会自动读取项目根目录下的.devcontainer/devcontainer.json文件来启动和配置开发容器。基于已下载的镜像，创建配置文件并添加以下内容：

{
  "name": "Autoware Universe Dev",
  "image": "ghcr.io/autowarefoundation/autoware:universe-devel-20250903-amd64",

  // 设置容器内的工作目录
  "workspaceFolder": "/home/developer/autoware",

  // 端口转发配置，用于支持可视化工具和服务访问
  "forwardPorts": [8080, 9090, 50051],

  // 目录挂载配置，实现本地与容器间文件同步
  "mounts": [
    {
      "type": "bind",
      "source": "${localWorkspaceFolder}",
      "target": "/home/developer/autoware"
    }
  ],

  // 容器创建后的初始化命令（可选）
  //   "postCreateCommand": "source /opt/ros/humble/setup.bash && cd /home/developer/autoware && echo 'Dev container ready!'",

  // 推荐的VS Code扩展配置
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.cpptools-extension-pack",
        "ms-vscode.cmake-tools",
        "ms-python.python",
        "ms-python.debugpy",
        "ms-python.vscode-python-envs",
        "Ranch-Hand-Robotics.rde-pack"
      ],
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  },

  // 容器运行参数配置
  "runArgs": [
    "--privileged", // 特权模式，用于访问GPU、串口等硬件设备
    "-e",
    "DISPLAY=${env:DISPLAY}",
    "--volume=/tmp/.X11-unix:/tmp/.X11-unix:rw"
  ]
}

🔍 配置项说明：

• image: 指定使用的 Docker 镜像
• workspaceFolder: 定义容器中的工作目录路径
• mounts: 配置本地目录与容器目录的绑定挂载
• forwardPorts: 指定需要转发的端口号，便于访问容器内服务
• extensions: 推荐安装的开发扩展列表,可以通过在侧边栏的扩展里面对着想要添加的插件右键并点击添加到devcontainer.json。
• runArgs: 容器运行时的附加参数

---

3. 启动开发容器

1. 在 VS Code 中打开项目目录
2. 点击左下角的绿色远程连接图标（或使用快捷键Ctrl+Shift+P）
3. 在命令面板中输入并选择：Dev Containers: Reopen in Container（中文：在容器中重新打开）
4. VS Code 将执行以下操作：
   • 基于指定镜像启动容器
   • 挂载配置的本地目录
   • 自动安装推荐的扩展插件

4、允许 root 用户使用X11

xhost +local:root

---

三、项目开发与编译调试

完成上述配置后，您就已经进入了一个完整的 Docker 开发环境。现在可以像在原生 Linux 系统中一样进行开发工作。由于我们已将~/work/autoware目录挂载到容器内，因此可以在容器内外同步访问项目文件。

1. 克隆项目源码

在容器终端中执行以下命令获取 Autoware 源代码（也可以在宿主机挂载的~/work/autoware目录下载数据）：

git clone https://github.com/autowarefoundation/autoware.git
cd autoware
mkdir src
vcs import src < autoware.repos

2. 更新系统环境并安装依赖

确保开发环境处于最新状态并安装所有必要的依赖项：

sudo apt update && sudo apt upgrade
rosdep update
rosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO

3. 编译项目

使用colcon工具编译整个 Autoware 项目：

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

通过以上配置，您就可以在 VS Code 中享受容器化开发带来的环境隔离和一致性优势，同时保持与本地开发环境的无缝集成。