从踩坑到落地：全志 H618 Android12 Docker 编译环境完整搭建指南

本文为真实开发踩坑全记录，覆盖 Linux 服务器、Windows WSL2 双场景，解决编译环境依赖、权限报错、环境持久化、跨系统移植全流程问题，看完就能从零搭建一套可复用的 Android 编译环境。

前言

做嵌入式 Android 系统开发的朋友都懂：Android 源码编译对环境依赖极其苛刻，不同 Android 版本要求的 JDK、Python、系统工具链天差地别。

不同版本的ubuntu系统环境和依赖都不一样。
直接在物理机装环境，很容易把系统搞乱；用 VMware 虚拟机，不仅启动慢、资源占用高，共享文件夹还一堆权限坑。
而 Docker 容器化方案，能完美解决这些痛点：环境隔离、秒级启动、资源占用极低、环境可一键移植，是编译 Android 源码的最优解。

本文就以全志 H618 平台 Android12.0 源码编译为例，把从 0 到 1 搭建 Docker 编译环境的完整流程、所有踩过的坑和解决方案，一次性全部分享给大家。

一、先搞懂：Docker 编译 Android，比 VMware 好在哪？

很多朋友会问，我用 VMware 装 Ubuntu 也能编译，为什么非要用 Docker？一张表给你讲透差异：

对比维度	Docker 容器	VMware 虚拟机
启动速度	秒级启动，瞬间进入编译环境	开机几十秒到几分钟，需等待完整系统启动
资源占用	仅占用编译所需资源，无冗余系统进程，内存占用极低	完整系统本身就要吃掉 2-4G 内存，后台进程大量占用资源
文件互通	直接挂载宿主机目录，宿主机改代码，容器里直接编译，无延迟	共享文件夹卡顿、权限坑多，文件传输麻烦
环境一致性	镜像一次配置，永远一致，删了重开还是一模一样的环境	长期使用环境会变脏，依赖冲突频发，重装需从头配置
编译性能	接近原生物理机性能，IO 损耗极低	有明显性能损耗，编译速度普遍比 Docker 慢 20% 以上
环境移植	一个 tar 包就能跨机器、跨系统迁移	虚拟机镜像动辄几十 GB，迁移极其麻烦

结论：单纯编译 Android / 嵌入式 SDK，Docker 全方位吊打 VMware，完全没必要用虚拟机。

二、环境准备

本文覆盖两个最常用的开发场景，大家按需选择即可：

1.Linux 服务器场景：Dell PowerEdge R720xd 物理服务器，Ubuntu 系统

2.Windows 办公机场景：Win10/Win11 台式机 / 笔记本，用 WSL2+Docker 实现编译

前置要求

•Linux 服务器：已安装 Docker，内存≥16GB（推荐 32GB），CPU 核心数≥8 核

•Windows 机器：已开启虚拟化，Win10 2004+/Win11 系统，内存≥16GB，源码存放于 NVMe SSD（机械硬盘编译会巨慢）

三、Linux 服务器：Docker 编译环境完整搭建

这是最稳定、性能最好的场景，我们从拉取基础镜像开始，一步步搞定完整编译环境。

3.1 拉取适配的基础镜像

Android12.0 编译最适配的 Ubuntu 版本是 20.04/22.04，这里我们选择长期支持的 ubuntu:22.04：

 

# 拉取官方基础镜像sudo docker pull ubuntu:22.04# 验证镜像是否拉取成功sudo docker images

 

3.2 正确启动容器（避坑核心）

很多新手第一个坑就踩在这里：启动容器的命令不对，要么退出就删环境，要么源码挂载不上。

错误命令（退出就删环境）

 

# 带--rm参数，退出容器会自动删除，装的依赖全没了！sudo docker run -it --rm -v $(pwd):/h618-android12.0 -w /h618-android12.0 ubuntu:22.04

 

正确命令（持久化容器，环境永久保留）

 

# 给容器命名，不带--rm，退出后容器仅停止，环境完全保留sudo docker run -it --name h618-build   -v $(pwd):/h618-android12.0   -w /h618-android12.0   --privileged   ubuntu:22.04

 

命令参数详解：

•-it：以交互式终端进入容器

•--name h618-build：给容器命名，方便后续管理

•-v 宿主机路径:容器路径：把宿主机的 Android 源码目录挂载到容器内

•-w：指定进入容器后的默认工作目录，直接进入源码根目录

•--privileged：给容器最高权限，避免编译过程中权限不足

3.3 容器内：全量编译依赖安装（一次性避坑）

进入容器后，第一步就是安装 Android12 编译所需的所有依赖，把后续会踩的坑一次性解决：

 

apt install git bc bison build-essential curl flex libsdl1.2-dev apt install g++-multilib gcc-multilib gnupg gperf libncurses5-dev apt install imagemagick lib32ncurses5-dev lib32readline-dev squashfs-tools apt install lib32z1-dev liblz4-tool xsltproc libssl-dev libwxgtk3.0-gtk3-devapt install libxml2 libxml2-utils schedtool lzop pngcrush rsync apt install yasm zip zlib1g-dev python device-tree-compiler apt install python-pip gawk openjdk-8-jdk u-boot-tools patchelf expectpip install pyelftools

 

3.4 容器内：前置配置修复（解决必现报错）

安装完依赖，先做两个配置修复，否则编译一定会报错：

 

# 1. 修复git安全目录问题，解决挂载目录的git权限报错git config --global --add safe.directory /h618-android12.0# 2. 配置git换行符，避免Windows和Linux换行符冲突导致脚本报错git config --global core.autocrlf input

 

3.5 高频报错合集 & 解决方案

这里把编译过程中 99% 会遇到的报错，全部整理好，遇到直接复制命令解决：

报错 1：python: command not found

•原因：Ubuntu22.04 默认只有 python3 命令，没有 python 命令，老的编译脚本只认 python

•解决方案：

 

ln -s /usr/bin/python3 /usr/bin/python# 或者直接安装python-is-python3包（上面依赖安装已经包含）

 

报错 2：fatal: detected dubious ownership in repository at 'xxx'

•原因：容器内 root 用户，不信任宿主机挂载的 git 仓库目录

•解决方案：上面的 git safe.directory 配置命令

报错 3：xxd: command not found

•原因：缺少 xxd 工具，编译 bootloader 必备

•解决方案：apt install -y xxd（上面依赖安装已经包含）

报错 4：cpio: not found

•原因：缺少 cpio 工具，编译内核和 boot.img 必备

•解决方案：apt install -y cpio（上面依赖安装已经包含）

报错 5：permission denied while trying to connect to the Docker daemon socket

•原因：当前普通用户没有权限访问 Docker 的 socket 文件

•解决方案：把当前用户加入 docker 用户组，永久免 sudo

 

# 创建docker组（若不存在）sudo groupadd docker# 把当前用户加入docker组sudo usermod -aG docker $USER# 关键：退出当前SSH会话重新登录，权限才会生效

 

报错 6：Unable to find image 'xxx:latest' locally

•原因：镜像标签不对，Docker 默认找 latest 标签，而你的镜像标签不是 latest

•解决方案：运行命令必须带上完整的镜像标签，比如h618-android-build:v1，不能只写镜像名

3.6 容器的日常使用命令

 

# 退出容器：exit# 下次重新进入容器（环境全保留）sudo docker start h618-buildsudo docker exec -it h618-build bash# 停止容器sudo docker stop h618-build# 删除容器（环境乱了可以删了重建）sudo docker rm -f h618-build

 

四、Windows 办公机：WSL2+Docker 编译环境搭建

很多朋友只有 Windows 办公机，也想编译 Android 源码，这里给大家一套替代 VMware 的最优方案，性能接近原生 Linux。

4.1 开启 WSL2（前置步骤）

1.以管理员身份打开 PowerShell，执行安装命令：

 

wsl --install

 

2.命令会自动启用 WSL、虚拟机平台，下载安装 Ubuntu，完成后重启电脑

3.重启后会弹出 Ubuntu 窗口，设置用户名和密码（用户名必须小写字母开头，只能包含小写字母、数字、下划线、短横，否则会报错）

4.验证 WSL 是否正常：

 

wsl -l -v

 

看到Ubuntu  Running  2，说明 WSL2 安装成功

4.2 Docker Desktop 安装与配置

1.官网下载 Docker Desktop 安装包，双击安装，必须勾选Use WSL 2 instead of Hyper-V

2.安装完成后重启电脑，打开 Docker Desktop

3.进入 Settings → General，确认勾选Use the WSL 2 based engine

4.进入 Settings → Resources → WSL Integration，勾选 Ubuntu，保存并重启 Docker

5.验证 Docker 是否正常：

 

docker run hello-world

 

出现欢迎信息，说明 Docker 安装成功

4.3 启动编译容器（和 Linux 服务器完全一致）

PowerShell 进入你的 Android 源码所在目录，执行启动命令：

 

docker run -it --name h618-build `  -v D:h618-android12.0:/h618-android12.0 `  -w /h618-android12.0 `  --privileged `  ubuntu:22.04

 

后续的依赖安装、配置修复、编译命令，和 Linux 服务器场景完全一致。

4.4 更稳的替代方案：直接用 WSL2 原生编译

如果 Docker Desktop 启动失败，完全可以不用 Docker，WSL2 本身就是完整的 Linux 系统，直接在里面安装依赖编译即可：

1.PowerShell 输入wsl进入 Ubuntu 系统

2.执行本文 3.3 的全量依赖安装命令

3.进入源码目录：cd /mnt/d/h618-android12.0（Windows 的 D 盘对应 WSL 里的 /mnt/d/）

4.执行编译命令即可，效果和 Docker 完全一致

五、编译环境持久化与跨系统移植

环境配置好之后，我们可以把它打包成自定义镜像，实现一劳永逸，还能跨机器、跨系统移植。

5.1 把配置好的容器打包成自定义镜像

1.先保持容器处于运行状态，不要退出

2.新开一个终端窗口，执行 commit 命令，把容器打包成镜像：

 

# 格式：docker commit 容器名 镜像名:标签sudo docker commit h618-build h618-android-build:v1

 

3.验证镜像是否打包成功：

 

sudo docker images

 

能看到h618-android-build:v1，说明打包成功

5.2 自定义镜像的使用

以后编译，直接用这个打包好的镜像启动容器，进去就能直接编译，所有依赖、配置都已经预装好：

 

sudo docker run -it --rm   -v $(pwd):/h618-android12.0   -w /h618-android12.0   h618-android-build:v1

 

5.3 镜像跨系统移植

方案一：离线导出 / 导入（推荐，无网络也能用）

1.源机器导出镜像为 tar 包：

 

# 若是tar.gz包，先解压gunzip h618-android-build-v1.tar.gz# 导入镜像sudo docker load -i h618-android-build-v1.tar

 

2.把 tar 包通过 U 盘、scp、局域网共享等方式，传输到目标机器

3.目标机器导入镜像：

 

# 若是tar.gz包，先解压gunzip h618-android-build-v1.tar.gz# 导入镜像sudo docker load -i h618-android-build-v1.tar

 

4.验证：sudo docker images能看到镜像，说明移植成功

方案二：Docker Registry 推送（适合有网络、多人共享）

1.给镜像打仓库标签（以 Docker Hub 为例）：

 

sudo docker tag h618-android-build:v1 你的DockerHub用户名/h618-android-build:v1

 

2.登录 Docker Hub 并推送：

 

sudo docker tag h618-android-build:v1 你的DockerHub用户名/h618-android-build:v1

 

3.目标机器直接拉取镜像：

 

sudo docker pull 你的DockerHub用户名/h618-android-build:v1

 

六、最终编译验证

环境全部配置好之后，进入容器的源码目录，执行标准 Android 编译命令即可：

 

SDK$ source build/envsetup.shSDK$ lunch apollo_p2-userdebugSDK$ make installclean -j32

 

七、核心避坑总结

1.启动容器不要随便加--rm参数，除非是临时测试，否则退出容器环境就会被删除

2.Ubuntu22.04 默认没有python命令，必须安装python-is-python3或者做软链接

3.挂载的 git 仓库目录，必须配置git safe.directory，否则一定会报权限错误

4.Docker 权限问题，优先把用户加入 docker 用户组，不要每次都用 sudo

5.镜像操作必须带上完整标签，Docker 默认找latest标签，很容易踩坑

6.Windows 下源码不要放在机械硬盘，必须放在 NVMe SSD，否则编译速度会慢到离谱

结尾

以上就是全志 H618 Android12 Docker 编译环境的完整搭建流程，从踩坑到落地，所有细节和解决方案都毫无保留地分享给大家。
按照这个流程操作，不管是 Linux 服务器还是 Windows 办公机，都能快速搭建一套稳定、可复用的 Android 编译环境，再也不用为环境问题头疼。

如果大家在操作过程中遇到任何问题，欢迎在评论区留言交流，我会一一回复。如需镜像，请留言。

审核编辑 黄宇