📚 课程目录第3章 Apollo开发环境搭建

3. Apollo开发环境搭建

说实话，搭建开发环境这件事，看着简单，但坑是真不少。我见过太多同学卡在这一步，源码下载了三天三夜，编译报错到怀疑人生。今天我就把我在项目中踩过的坑、积累的经验，一次性给你讲清楚。

核心要点：Apollo 8.0 及以上版本，官方推荐使用 Ubuntu 22.04 + ROS2 Humble。别再用 Ubuntu 18.04 了，那是老黄历了。

3.1 Ubuntu 22.04 系统配置

我个人习惯用 Ubuntu 22.04 LTS 桌面版。为什么？因为调试时方便看图形界面。如果你在服务器上部署，用 Server 版也行，但桌面版会让你少走很多弯路。

3.1.1 基础环境准备

装完系统第一件事，换源。别问为什么，问就是下载速度。我曾经在项目现场用默认源下载依赖，等了两个小时……后来学乖了，先换清华源或阿里源。

# 备份原源
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 替换为清华源（Ubuntu 22.04）
sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list
sudo sed -i 's/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list

# 更新
sudo apt update && sudo apt upgrade -y

3.1.2 安装必要工具

嗯，这里要注意，有些工具是编译 Apollo 必须的，缺一个都不行。

sudo apt install -y \
    git \
    vim \
    curl \
    wget \
    build-essential \
    cmake \
    python3-pip \
    python3-venv \
    ninja-build \
    pkg-config \
    libssl-dev \
    libffi-dev \
    libncurses-dev \
    libsqlite3-dev \
    libbz2-dev \
    libreadline-dev \
    libgdbm-dev \
    liblzma-dev \
    tk-dev \
    uuid-dev \
    zlib1g-dev

我的经验：装完这些后，记得重启一下系统。有些内核模块需要重新加载，不重启的话，后面编译可能会报一些莫名其妙的错。

3.2 ROS2 Humble 安装

Apollo 8.0 开始全面拥抱 ROS2。为什么选 Humble？因为它是 Ubuntu 22.04 的 LTS 版本，稳定，社区支持好。我去年在一个量产项目里用的就是 Humble，跑了半年没出过问题。

3.2.1 设置语言环境

ROS2 对 locale 有要求。我记得有一次没设对，编译时一堆警告，看着就烦。

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

3.2.2 添加 ROS2 源

# 添加 ROS2 GPG key
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

# 添加源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

sudo apt update

3.2.3 安装 ROS2 Humble

这里我建议装桌面版，包含 RViz2 等可视化工具。调试时特别有用。

sudo apt install -y ros-humble-desktop python3-colcon-common-extensions

避坑指南：我曾经遇到过安装后找不到 ros2 命令的情况。原因是忘了 source 环境变量。记得把下面这行加到 ~/.bashrc 里：

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

3.3 Apollo 源码编译与部署

终于到重头戏了。Apollo 的编译，说白了就是一套 Docker + Bazel 的组合拳。但别怕，跟着我一步步来。

3.3.1 下载源码

Apollo 的仓库很大，建议用浅克隆，不然下载到你怀疑人生。

git clone --depth=1 https://github.com/ApolloAuto/apollo.git
cd apollo

3.3.2 安装 Docker

Apollo 所有依赖都在 Docker 里。你想想看，这样多好——不管你的宿主机是什么环境，Docker 里都是一致的。

# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

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

# 退出重新登录，或者执行
newgrp docker

3.3.3 启动 Apollo 开发容器

# 进入 Apollo 目录
cd apollo

# 启动开发容器
./apollo.sh start

# 进入容器
./apollo.sh enter

注意：第一次启动容器会拉取镜像，大概 2-3GB，请确保网络通畅。我建议用代理或者换国内镜像源。

3.3.4 编译 Apollo

在容器内执行编译。这里我推荐用 GPU 模式，如果你有 NVIDIA 显卡的话。没有 GPU 也能编译，但有些模块（如感知）会跑不了。

# 编译全部模块（GPU 模式）
./apollo.sh build_gpu

# 或者只编译 CPU 版本
./apollo.sh build_cpu

编译时间取决于你的机器配置。我见过最快的——一台 128 核的服务器，15 分钟搞定。也见过笔记本编译了 2 小时的。嗯，耐心等吧。

3.3.5 验证部署

编译完成后，启动 Dreamview 看看效果。

# 启动 Dreamview
./scripts/bootstrap.sh start

# 打开浏览器访问
# http://localhost:8888

如果看到 Dreamview 界面，恭喜你，环境搭建成功了！

3.4 知识体系总览

下面这张图，是我自己总结的 Apollo 开发环境搭建的完整流程。你照着这个走，基本不会迷路。

3.5 常见问题与避坑

问题	原因	解决方案
编译时提示 Bazel 版本不对	Apollo 对 Bazel 版本有严格限制	使用容器内的 Bazel，不要用宿主机自带的
Docker 拉取镜像超时	网络问题	配置 Docker 镜像加速器（阿里云/中科大）
Dreamview 页面空白	端口被占用或未启动	检查 8888 端口，重启 bootstrap
ros2 命令找不到	未 source 环境变量	检查 ~/.bashrc 中是否有 source 语句

我的经验：如果你在编译过程中遇到「Killed」错误，八成是内存不够。Apollo 编译很吃内存，建议至少 16GB。我曾在 8GB 的笔记本上编译，直接卡死。解决办法：增加 swap 空间，或者减少并行编译任务数。

# 增加 swap（以 8GB 为例）
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

好了，环境搭建就到这里。这套流程我反复验证过多次，只要按步骤来，基本不会出问题。如果遇到奇怪的错误，先检查是不是漏了某个依赖，八成是它。