Android 8.0源码编译实战：环境、构建参数与产物验证

自己动手编译 Android 8.0 源码这件事，我在不同机器上一共折腾过四五轮，从最早用一台 8G 内存的老笔记本硬扛，到后来专门配了一台多核实测机，中间踩的坑能写满一页纸。起因很简单：日常开发中总会碰到一些读文档读不明白的东西，比如系统服务到底是哪个进程、某个权限检查卡在哪一层、预置应用为什么装上了却起不来。只翻文档和进度表，永远只能看到轮廓。真正把编译 Android 8.0 源码跑通一遍，你手里会多出两样东西：一份可以随便改、随便加日志、随便塞调试代码的完整系统镜像，以及一套能让你把系统启动链路从头看到尾的产物。这篇内容就是给想迈这一步的人写的，不管你是刚学会在 Linux 下敲命令的新手，还是已经写过几个系统层模块、但一直用现成固件调试的老手，都能从这里找到对得上的操作细节和真实会卡住的地方。

1. 先想清楚：为什么值得花几个小时编译一份系统镜像

1.1 编译源码带来的三个实际能力

很多人对"编译源码"的想象是拿到一个能刷进手机的包，其实那只是最表面的收益，而且往往是最后才用得上的部分。真正值钱的是过程里暴露出来的东西。

第一是可观测性。拿到完整源码之后，你可以在任何一层插入日志。比如某个广播为什么没被接收，你可以在广播分发的关键节点打一行输出，然后重新编译、重新跑，直接看到实际的分支走向，而不是靠猜。这种能力用现成固件是拿不到的。

第二是可修改性。想在系统启动早期改一个属性默认值、想看某个服务在开机流程里被拉起的顺序、想验证一个自己写的系统服务能不能正常注册，都需要一份从源码编出来的镜像。你甚至可以做减法：砍掉不需要的模块，观察系统还能不能正常起来，这个过程中你对模块依赖关系的理解会迅速超过读十篇文档。

第三是可控的复现环境。设备上出问题，最怕的是"改一改又好了，说不清为什么"。源码编译给你的是一套完全闭环的环境：代码版本、编译工具链、产物路径全部明确，出问题可以一行行追，可以二分定位，可以反复验证。

提示：如果你只是想看看 Android 的代码长什么样，克隆几个关键模块的仓库就够了，不需要全量编译。全量编译的成本主要花在磁盘和耐心上，先确认自己确实需要一份可运行镜像，再开工。

1.2 该不该动手：按需求分成三类人

第一类是系统层开发，日常要改 framework、系统服务、HAL 接口，或者做定制化功能。这类人逃不掉，早点跑通越省事。

第二类是应用开发但想深入理解平台行为。比如你被一个后台限制、一个权限弹窗、一个进程保活问题折磨过，想搞清楚系统到底怎么判定的。这类人不必强求完整流程跑通，可以从源码阅读开始，需要动手验证的时候再编译单个模块，用增量编译节省时间。

第三类是纯好奇。这类人我给的建议是：先估一下自己机器的配置，如果内存低于 16G、硬盘剩余空间低于 150G，别急着开始，很容易卡在编译中途被打断，挫败感极强。这不是技术难度问题，是资源问题。

我自己第一轮就属于第三类，8G 内存的笔记本编译到 jack 阶段反复被系统杀掉进程，折腾了整整两天，最后是靠加 swap 文件硬撑过去的，那体验很不体面。

1.3 关于 Android 8.0 这个版本的特殊性

选 8.0 而不是更新的版本，有很现实的理由。它是编译体系的一个"过渡期"版本：既保留了传统的 Make 主导流程，又开始引入新的构建系统。这意味着你能同时看到两套东西，学习价值反而比后来的纯新体系更高。

但代价是它处在一个工具链要求比较挑剔的位置。它对 JDK 版本、对宿主机系统版本、对依赖库的版本都有比较明确的要求，用太新的发行版会撞上一堆兼容性问题。这也是为什么很多人一上手就在环境准备阶段卡住。下面我把环境准备这一块拆得细一点，因为这里省下的时间，后面能还给你的不止一倍。

2. 环境准备：硬件算账、系统选择与依赖安装

2.1 硬件资源怎么算，别凭感觉配

编译这件事最忌讳拍脑袋。我把几个关键资源的账算给你听。

磁盘：源码本体（含.repo目录）下载完大概在 60G 到 80G 之间，具体取决于你拉的分支和是否包含历史记录。编译产物out目录第一次编完通常 40G 到 60G，如果你同时保留多个目标（比如编译了 ARM 又编译了 x86 模拟器目标），占用会翻倍。再加上 ccache 缓存，我建议预留 200G，少于 150G 会在某个时刻突然报"设备上没有空间"，而且报错位置往往很随机，排查起来很费神。

内存：这是最容易低估的一项。官方给的参考值我只当作下限看。实际经验是：编译过程里最吃内存的是 Java 代码编译环节的常驻服务，它需要一块独立的堆空间，而链接和打包阶段又需要额外的缓冲。16G 是能跑通的底线，32G 比较舒服，64G 基本不用操心。如果只有 16G，务必配一块足够大的交换分区，否则很容易在编译进行到七八成的时候被系统的内存回收机制直接终止进程，前面的时间全白费。

CPU：核心数直接决定并行度。8 核和 16 核的差距在首次全量编译上非常明显。但要注意，并行度不是越高越好，它跟内存是绑定的，每提高一个并行任务，就要多预留一部分内存给它。

下面这张表是我在不同配置上实测的大致感受，时间取的是首次全量编译（不含下载）：

注意：上表里的并行度是保守值。真正的判断依据是"内存除以并行任务数"，每个任务至少要能分到 1.5G 到 2G 的余量，低于这个数就容易在链接阶段爆内存。

磁盘类型的影响比很多人想象的大。源码目录里有几十万个小文件，机械硬盘在这种随机读写场景下会让编译时间成倍增加，SSD 是硬性要求，NVMe 更好。

2.2 宿主系统与文件系统的选择

宿主系统这块，我的建议是跟着源码版本走，不要图新鲜用最新的发行版。Android 8.0 的构建脚本和预编译工具链是按当时的 LTS 版本调过的，用更新的系统会遇到两类麻烦：一类是依赖库名字变了（比如某些库把版本号从名字里去掉了，导致脚本里写的旧名字找不到），另一类是默认的编译器版本太新，对老代码的语法检查更严格，直接编译报错。

我自己的做法是装一个长期支持版的服务发行版，装完先不升级到最新，保持在一个相对稳定的状态。如果你手上只有比较新的系统，也不是不能做，但要提前做好心理准备，可能需要在依赖安装环节手动补齐几个旧版本的库，或者在编译时显式指定编译器路径。

文件系统这一项值得单独提醒：源码树里有大量文件名只差大小写的情况，而 Android 的构建对文件名大小写敏感。如果你把源码放在一个大小写不敏感的分区上（比如某些外接盘默认的格式），会出现莫名其妙的"找不到文件"或者"重复定义"。解决办法很简单：把源码放在系统原生的分区上，不要在中间做挂载转换。

另外分区格式上，建议用能支持大文件数和大量小文件的方案。我曾经在一个默认 inode 数量偏少的分区上编译，跑到一半报"无法创建文件"，查了半天才发现不是空间不够，是 inode 用光了。这类问题排查起来非常耽误时间，提前避开比事后补救划算得多。

swap 的设置简单提一下，因为很多人在 16G 机器上需要它：

# 创建一个 16G 的交换文件（路径按自己情况改） sudo fallocate -l 16G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 验证 free -h

如果要让它开机自动生效，需要写进/etc/fstab。不过 swap 只是兜底，它的速度远低于物理内存，如果你的编译过程频繁依赖 swap，说明内存配置本身就不够，编译时间会被拉得很长。

2.3 依赖包与 JDK 版本：这里最容易翻车

依赖包的大致范围是编译工具、压缩库、图形库的开发头文件、多架构支持库这几类。一次性装齐最省事，缺一个都会在编译到某个奇怪的位置时才报错。大致需要的是：版本控制工具、构建基础套件、词法与语法分析工具、压缩库开发包、32 位兼容库、图像与 XML 处理库、以及一个编译缓存工具。

这里我不逐条列包名，因为不同发行版的包名差异很大，照着抄反而容易错。更靠谱的做法是去源码树里找官方给的依赖安装脚本，那个脚本会针对你的发行版做判断，直接跑就行。

JDK 是重灾区。Android 8.0 的构建脚本对 Java 版本有硬性检查，版本不对会直接报错退出，措辞大概是"你使用了错误版本的 Java"。你需要的是JDK 8，而且要注意是 64 位版本。有些发行版默认装的是更高版本，或者同时装了多个版本但环境变量指向了错误的那个。

装好之后一定要验证，别嫌麻烦：

java -version javac -version echo $JAVA_HOME

三个输出要一致，都指向同一个 JDK 8 的安装目录。如果java和javac指向不同 JDK，编译过程中会出现非常诡异的错误，比如某个工具能跑但另一个报找不到类。

提示：很多发行版允许同时安装多个 JDK 版本，通过软链接切换。切换之后记得重新打开终端，让环境变量生效，否则你在旧终端里看到的还是旧版本。

还有一个经常被忽略的点：Python 版本。这套构建脚本里有一部分是老式的 Python 2 代码，如果你的系统默认只有 Python 3，需要额外装一个 Python 2 并保证它在路径里能被找到。这个坑很典型，报错信息通常是语法错误，看起来像是源码出了问题，其实是解释器版本不对。

3. 源码获取与目录结构：先建立地图意识

3.1 拉代码前的准备工作

整套源码由成百上千个代码仓库组成，靠一个专门的仓库管理工具来批量操作，单靠版本控制工具本身是管不过来的。所以第一步是把那个管理工具装到系统路径里。

安装大致分三步：下载脚本、给执行权限、放到PATH里能找到的目录。装完执行一下版本命令，能输出内容就说明装好了。

接下来是初始化。初始化要指定清单仓库的地址和分支，这里有两个实操建议：

第一，先在国内的开源镜像站上找对应的清单地址。源码体量太大，从远端直接拉可能要跑一整天甚至中途断掉。镜像站一般会提供完整的同步方案，速度差异是数量级的。

第二，初始化时不要把历史记录全拉下来。加一个只拉单个提交历史的参数，能省掉大量体积和下载时间。日常编译和调试根本用不到完整历史。

初始化命令的大致形状是这样：

mkdir ~/aosp && cd ~/aosp repo init -u <清单仓库地址> -b <目标分支> --depth=1

分支这里要说明一下：Android 8.0 对应一系列带有小版本号的标签，选择哪个取决于你要不要包含后续的修订。如果是第一次尝试，选一个后期的修订版本会更稳，因为前面的版本里有些已知问题需要手动打补丁。具体标签名就以源码站上列的为准，一个一个试没必要。

3.2 同步过程中的现实问题

初始化完成之后开始同步。同步的并发数不要开太高，网络带宽是瓶颈，并发太高反而容易触发对端的限流，导致频繁重试，总耗时更长。我一般用中等并发，然后接受"挂机一晚上"这个事实。

同步过程中断是常态，不要慌，直接重新执行同步命令，它会接着已经下载完的部分继续。关键是要注意看最后几行输出，确认是否所有仓库都完成了同步。如果有几个仓库反复失败，可以单独针对它们做同步。

全部同步完之后，先别急着编译，做两件事：

一是确认磁盘剩余空间。前面说 200G 是底线，这时候看一眼还剩多少心里有数。

二是确认目录完整性。源码根目录下应该能看到构建脚本、清单文件、各个分组目录。如果发现某个顶层目录是空的，说明对应的仓库没同步下来，这时候编译必然失败，早点发现比编到一半发现好。

3.3 目录结构扫一眼，后面找东西快很多

不用背目录，但有意识地建立一个大致的方位感，会让你后面查文件、改代码、找产物快非常多。我把几个你会反复用到的位置点一下。

构建脚本所在的位置：根目录下有一个用于设置环境的脚本，每次新开终端都要执行一次，它会把各种便捷命令注入当前 shell。这个脚本执行之后，你才能用那些简写的构建命令。

设备配置目录：包含各个目标设备的配置文件，lunch列表就是从这些目录里扫出来的。你想知道某个目标叫什么名字，来这里看。

构建产物目录：编译完成后所有东西都在out下面，按目标设备分子目录。这个目录会非常大，如果你需要反复编译不同目标，记得定期清理。

预编译工具目录：里面有编译器、缓存工具、签名工具等等。你偶尔会需要直接调用这里的工具，比如手动设置缓存大小，或者手动终止某个常驻的编译服务。

系统镜像的打包规则：分布在各个模块的构建文件里，定义了什么进系统分区、什么进数据分区。你想知道某个文件为什么没进镜像，就顺着这条线找。

提示：养成一个习惯，每次改动后只做增量编译，不要动不动删out目录重来。清理一次意味着后面所有东西都要重新编一遍，时间成本极高。只有在出现无法定位的链接错误、或者切换分支导致产物混乱时，才值得清理。

4. lunch、并行度与缓存：把编译这步走稳

4.1 选择目标：lunch 里面的门道

设置环境之后，输入lunch会列出所有可选目标。列表很长，新手很容易在这里懵。你需要理解名字的构成方式，它大致是"设备代号 + 架构 + 构建类型"的组合。

构建类型有几种，常用的两类：一类带调试支持，方便你挂调试器、看详细日志；一类是偏发布形态的，运行更接近真实设备但调试不方便。第一次编译强烈建议选带调试支持的类型，编出来的东西能用、能调、出问题也容易查。

如果你的目的是在模拟器里跑起来验证，选模拟器对应的架构目标即可，编译快、启动快、验证方便。如果你的目的是刷到真实设备上，那就要选对应设备的代号，而且要注意有些设备的配置需要额外的专有驱动文件，这些东西不在公开源码里，缺了会编译不过或者编出来跑不起来。

第一次动手我建议先走模拟器这条路。理由很实在：全流程能完整跑通，产物能立刻验证，不用碰任何刷机相关的风险操作。等这套流程熟了，再考虑真机。

选定目标之后，后面的构建命令都会作用于这个选择。如果中途想换目标，重新执行选择命令即可，但要注意产物目录可能会混在一起，必要时分开不同目录。

4.2 并行度：给多少线程才合适

这一点我在第 2 节给了建议值，这里说一下背后的判断逻辑，因为每个人的机器不一样，照抄数值不可靠。

并行任务数的上限受两个因素约束：CPU 核心数和可用内存。CPU 决定你能并行多少份工作，内存决定你能同时养活多少份工作。取两者算出来的较小值。

经验公式是：并行数 ≤ 内存容量（G）÷ 2，同时并行数 ≤ CPU 物理核心数 × 1.5。取较小值，再往下调一点作为安全余量。

举个例子：16G 内存、8 核机器。按内存算是 8，按核心算是 12，取 8，再留余量，用 6 或 7。这个配置在链接和打包阶段如果不爆内存，就说明定得合适。

如果编译过程中出现进程被杀、或者系统明显卡到鼠标都动不了，立刻降低并行数重新来。硬扛只会让你在编译到 90% 的时候前功尽弃。

4.3 那个常驻的 Java 编译服务，必须单独调

Android 8.0 的 Java 编译走的是一个常驻服务，它在后台启动一个持续运行的进程来处理 Java 到字节码的转换。这个设计的好处是避免每次编译都重新启动虚拟机，坏处是它的内存限制是独立的，不受你上面调的并行数影响。

这是新手最容易卡住的地方。表现是：编译刚开始没多久，突然报错说服务启动失败，或者报内存不足。你去看系统内存明明还很富裕，因为限制是在服务内部设的。

解决办法分两步。第一步是给它显式指定堆大小，通过环境变量设置，值根据机器内存来定，16G 机器给 4G 到 6G 比较合适：

export ANDROID_JACK_VM_ARGS="-Dfile.encoding=UTF-8 -XX:+TieredCompilation -Xmx6g"

第二步，如果服务已经在后台跑着旧配置，改了环境变量它也不会自动更新。必须先把它停掉：

# 定位到预编译工具目录后执行 ./jack-admin kill-server

停掉之后再开始编译，新配置才会生效。这一步我见过太多人漏掉，改完变量发现没效果，然后开始怀疑是别的问题，绕一大圈。

还有一个配置文件的写法，有时候环境变量不生效（比如在某些构建入口下），可以在用户目录下建一个配置文件，把参数写进去，效果一样。

注意：这个服务的日志在用户目录下，如果报错信息看不太明白，去翻它的日志，里面通常会直白地写出是哪一项配置不够。

4.4 用编译缓存把第二次编译压到十几分钟

第一次全量编译最慢，但如果你只改了一个文件就想验证效果，等三小时是不可接受的。这时候缓存就派上用场了。

缓存工具会把你编译过的中间产物按内容哈希存起来，下次编译时如果输入没变，直接复用，跳过实际编译。对于"改一个文件→编译→验证→再改"这个循环，它能把时间从小时级压到分钟级。

配置方式是三个环境变量：

export USE_CCACHE=1 export CCACHE_EXEC=/usr/bin/ccache export CCACHE_DIR=~/.ccache

然后设置缓存大小。这一步很多人会漏，因为缓存默认容量很小，改几个文件就把缓存挤满了，等于白配。设置容量的命令要用源码树里自带的那个工具：

prebuilts/misc/linux-x86/ccache/ccache -M 50G

容量给多少：原则是不超过你磁盘空闲空间的一半。50G 是个比较通用的值，磁盘宽裕的话可以给到 100G。缓存目录放在系统分区而不是源码目录，这样清理源码目录的时候不会把缓存顺手删掉。

配好之后，第一次编译会稍微慢一点点（要写缓存），第二次开始就是肉眼可见的快。我实测过一次改动单个系统服务文件，从改完到编译出可刷的镜像，不到十五分钟。

5. 报错实录：这些坑我基本都踩过

5.1 内存与磁盘类问题

现象一：编译到一半突然退出，没有任何有效报错。这是最典型的被系统终止进程。去系统日志里搜一下，通常能看到进程被强制结束的记录。根源是内存不足。处理办法：降并行数、加大 swap、调小那个常驻服务的堆大小（但这会影响编译速度，权衡一下）。

现象二：报"设备上没有空间"，但df显示还有几十 G。这多半是 inode 用光了，而不是块空间不够。查一下 inode 使用率，如果接近 100%，只能换分区或者清理小文件。源码树里小文件极多，这个坑很隐蔽。

现象三：编译过程中途磁盘突然写满。原因通常是没有预料到的产物堆积。比如你反复编译不同目标，产物目录里留下了好几套。解决办法是在编译完成后手动清理不需要的产物目录，或者一开始就给足空间。

5.2 工具链与版本类问题

现象一：报 Java 版本不正确，直接终止。说明环境变量指向的 JDK 不对。按第 2 节的方法验证三个命令输出一致。注意如果你在同一个终端里切换过版本，可能需要重新打开终端。

现象二：报某个工具找不到，或者报语法错误但源码明明没问题。优先怀疑 Python 版本。老脚本需要 Python 2，如果系统默认只有 3，会以各种奇怪的报错形式表现出来。装一个 Python 2 并保证它在路径里靠前的位置。

现象三：编译到预编译的二进制工具时报"无法执行"或者版本不兼容。这类情况常见于用了过新的宿主系统，预编译工具依赖的库版本对不上。处理思路是补齐旧版本的兼容库，或者换一个更匹配的宿主系统。这个问题在环境准备阶段就该尽量规避，等编译到中途再处理很痛苦。

现象四：报一堆链接错误，指向某些预编译库。有时候是增量编译导致的产物不一致。先试着把相关模块的产物目录删掉重编，不行再考虑整体清理。

5.3 常见问题速查表

提示：排查的顺序建议是先看资源（内存、磁盘、inode），再看版本（JDK、Python、宿主系统），最后才怀疑源码。绝大多数失败都发生在第一类和第二类里，源码本身出问题的概率很低。

6. 产物验证与后续能做的实验

6.1 编完之后产物在哪、怎么用

编译成功之后，最后的输出会告诉你产物目录。进去之后按目标设备分子目录，你能看到几类关键文件：系统分区的镜像、数据分区的镜像、启动相关的小镜像，以及一堆中间文件。

如果走的是模拟器路线，这时候直接启动模拟器加载刚编出来的镜像就行。第一次启动会比较慢，因为要做初始化。所以第一次启动多等一会儿，不要以为卡死了就强制结束，我等过最久的一次将近十分钟。

启动起来之后，做几个验证动作确认这份镜像是你自己的：

• 看一眼系统版本信息的构建标识，应该和你编译时间对应。
• 在系统里找到你自己加的那行日志，确认改动生效了。
• 随便改一个系统应用的字符串，重新增量编译，再启动确认变化。

这三步做完，你就拥有了一套完整可迭代的环境。

如果是真机路线，那就要额外处理签名和刷写，涉及的风险明显更高，建议先把模拟器这条路走顺了再说。而且要注意，公开源码里缺少一部分硬件相关的专有文件，真机上有些功能可能不正常，这不是你编译错了。

6.2 手上有这套环境之后能干什么

这套环境真正的价值，在于它能让你用实验的方式回答问题。我列几个我自己做过的实验方向，你可以照着延伸。

开机流程可视化。在关键的启动节点加日志，打印时间戳和服务名字，你能清清楚楚看到整个启动顺序，以及每个阶段花了多久。这比看任何文档都直观。做完一次，你对"为什么某个服务在另一个服务之后才能用"这类问题会有完全不同的理解。

权限检查链路追踪。挑一个具体的权限，加日志跟一遍完整的判定流程，看看它是怎么一步步走到最终结论的。这个实验做完，很多"为什么我的应用拿不到这个权限"之类的疑问会自己消失。

模块裁剪实验。故意去掉系统里某个不关键的组件，看系统还能不能正常起来，起来之后哪些功能没了。用二分法做几次，你对模块依赖关系的认知会形成一张真实的图，而不是文档上那张示意图。

性能基线对比。同一套代码，改一个参数、换一种实现，编出来跑一遍对比启动耗时或某个操作的响应时间。这种实验用现成固件做不了，因为改不了底层。

6.3 我踩过的几个不太容易想到的坑

最后分享几个细节，都是常规教程里不会写、但实际会让你的时间打水漂的东西。

不要在编译过程中随便切换终端或者断网。有些构建步骤会依赖网络做校验，中途断掉可能导致产物不完整但流程不报错，最后你拿着一个有问题的镜像排查半天。编译期间就让它安安静静跑。

编译日志一定要留。把输出重定向到文件里，出问题时能翻回去看。终端有滚动缓冲上限，报错刷过去就找不回来了。我现在的习惯是每次编译都带上日志重定向，失败时直接在文件里搜关键字。

并行数不是越高越好，但也不是越低越稳。我见过有人因为怕爆内存，全程用极低的并行数，结果编译时间翻了三倍还多。正确的做法是先按公式定一个值，跑一次看表现，稳定就往上加一档试试，不稳就往下调。这台机器的最优值只对这台机器有效。

不要一遇到失败就全量清理。全量清理之后的第一次编译要重新走所有流程，时间成本极高。绝大多数失败都能通过清理局部产物解决，先定位到是哪个模块报错，只清那个模块。

改完那个常驻服务的配置之后，一定要确认旧进程真的死掉了。我遇到过一次停服务没成功，新配置没生效，白折腾两个小时。停完之后执行一下查询命令确认没有残留进程，再开始编译。

磁盘空间要给得比算出来的更宽裕。你的计算永远会漏掉一些东西：日志文件、缓存膨胀、临时产物。多留 50G 不会花你一分钱，但能帮你省掉一次"编译到最后一步失败"的崩溃体验。

这套流程跑通一次之后，后面就变成肌肉记忆了。真正花时间的是第一次的环境摸索，一旦打通，你手里就多了一个可以随时验证想法的沙盒，很多以前只能靠猜的问题，现在跑一遍就有答案。