跳至主要內容

查阅、下载与构建 AOSP 源码：环境与资源准备

知晏2026/8/9大约 13 分钟环境与源码准备AOSP源码下载构建模拟器环境准备

环境与源码准备：查阅、下载、构建与运行 AOSP

先按目标选择投入

常见误解正确理解
看 AOSP 源码必须有一台 400GB 磁盘、64GB 内存的机器官方 400GB/64GB 口径针对全量构建 main 分支；只查阅或只同步源码的投入小得多
下载 AOSP 就是 git cloneAOSP 由上千个 Git 仓库组成，官方用 repo 按 manifest 批量管理
编译产物必须放在源码目录里输出默认在 out/，可以通过 OUT_DIR 换到另一块盘，编译本身不污染源码
源码编译完就能直接跑模拟器模拟器需要匹配的产品目标和 KVM 加速；真机还需要解锁引导加载器与厂商闭源库

先明确自己属于哪个场景，再决定投入：

  1. 只想查代码、读调用链：浏览器加 Android Code Search 即可，不需要下载源码。
  2. 想本地搜索、看 Git 历史、用编辑器跳转：同步源码，16GB 内存加 250GB 磁盘起步。
  3. 想编译出系统镜像并在模拟器或真机运行：按官方全量要求准备 64GB 内存、400GB 磁盘和 Linux。
  4. 想定制 ROM、做系统开发：在第 3 项基础上，还要有一台受支持的目标设备或稳定的模拟器环境。

核心结论

  1. 查阅优先用 Android Code Search：零成本、可搜索、可跨引用、可切换分支。
  2. 下载用 repo：repo init -u <manifest> -b <tag> 之后 repo sync -c -j8；国内网络配合清华或中科大镜像。
  3. 编译按 source build/envsetup.sh → lunch → m → emulator 五步走；main 分支自带预构建的 JDK、Make 和 Python 3。
  4. 环境按场景分级：查阅零硬件要求；同步约 250GB 磁盘；全量构建官方要求 64 位 Linux、400GB 磁盘、64GB 内存。
  5. 真机运行比模拟器多两道门槛：解锁引导加载器，以及下载匹配版本的厂商闭源二进制。

从查阅到运行的完整路径

下面这张图把本章的主线串起来：先确定目标，再准备环境，然后同步、构建、运行，最后回到排障闭环。

一、查阅源码：最快的起步方式

先记住结论： 大多数阅读场景不需要本地源码，先用 Android Code Search。

Android Code Search 是官方代码搜索服务，覆盖 AOSP 全仓库，支持：

  • 按项目、目录浏览源码，例如直接打开 frameworks/base/services/core/java/com/android/server/wm/；
  • 全局搜索类名、方法名或字符串，并跳转定义与调用处；
  • 点击符号查看跨文件引用，适合追调用链；
  • 在页面右上角切换分支或 tag，例如从 main 切到 android-14.0.0_r75。

其他常用查阅入口：

入口特点适合
cs.android.com官方、可搜索、可跨引用、可切分支日常查代码和追调用链
github.com/aosp-mirror非官方 GitHub 镜像，单仓库好浏览快速打开某个仓库，不做全局搜索
本地源码树 + rg速度最快，支持正则和 Git 历史需要深查、改代码或对比版本

本地树里最常用的两个命令：

rg -n "addWindow" frameworks/base/services
git log --oneline -5 -- frameworks/base/services/core/java/com/android/server/wm/WindowManagerService.java

rg 回答“这段逻辑在哪里”，git log / git blame 回答“这段逻辑什么时候变成这样”。阅读方法本身可以继续看 Android Framework 到底是什么 中的“从 AOSP 根目录找到 Framework”。

二、设备要求：按场景给硬件预算

先记住结论： 先选场景，再买设备；不要一开始就按全量构建标准配机器。

场景CPU内存磁盘说明
只在线查阅任意任意任意浏览器即可
只同步源码并本地阅读双核以上16GB 起约 250GB 可用.repo 与工作区都占盘
全量构建 main 分支核数越多越好64GB 起400GB 以上官方最低要求
构建后跑模拟器支持虚拟化的 x86_6432GB 以上上述磁盘之外再加镜像空间需要 /dev/kvm
构建后刷真机同全量构建64GB 起400GB 以上另需一台受支持的目标设备

官方“针对 AOSP 开发进行设置”页面的口径（2025 年更新）：

  • 开发工作站需要 64 位 x86 Linux，glibc 2.17 及以上。
  • 检出和构建代码至少需要 400GB 可用磁盘，其中 250GB 用于检出，150GB 用于构建。
  • 至少 64GB 内存；Google 使用 72 核加 64GB 内存的机器，全量构建约 40 分钟；同样的 64GB 内存换成 6 核，全量构建约 6 小时。
  • 构建 Android 11 及以上版本，需要 Ubuntu 18.04 或更高版本。

注意两点：第一，64GB 是“全量构建”口径，只编译个别模块（m <模块名>）或更老的版本可以放宽，但不要因此挑战全量构建；第二，内存不足时会触发 swap，构建时间会成倍增长，所以“内存小但磁盘大”并不能替代内存。

三、设备环境要求：操作系统、磁盘与目标设备

操作系统

官方只完整支持 64 位 Linux。AOSP main 分支自带预构建的 OpenJDK、Make 和 Python 3，不需要额外安装；系统依赖包在 Ubuntu/Debian 上安装一次即可：

sudo apt-get install git-core gnupg flex bison build-essential zip curl \
  zlib1g-dev libc6-dev-i386 x11proto-core-dev libx11-dev lib32z1-dev \
  libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig

Windows 和 macOS 不在官方支持范围内。WSL2、虚拟机或容器属于自行折腾的方案，可以学，但要把“不受官方保证”当作边界，遇到诡异构建错误时优先回 Linux 验证。

磁盘与文件系统

先记住结论： 源码和构建产物要放在大小写敏感的 Linux 文件系统上，例如 ext4。

  • FAT、NTFS、exFAT 不支持符号链接和大小写语义，会导致 repo sync 失败或构建异常。
  • 磁盘要预留独立空间，构建期间 out/ 会剧烈膨胀；先运行 df -h 确认余量。
  • 想换盘可以设置输出目录：export OUT_DIR=/path/to/other/disk，注意两块盘的读写速度差异会影响构建时间。

模拟器与虚拟化

Linux 上运行 Android 模拟器需要 KVM 加速。构建机器如果跑在云服务器上，常常没有嵌套虚拟化，模拟器会极慢或直接起不来。启动前检查：

ls -l /dev/kvm
egrep -c '(vmx|svm)' /proc/cpuinfo

/dev/kvm 存在且 CPU 标志计数大于 0，才说明硬件虚拟化可用。

真机要求

官方支持刷 AOSP 的设备主要是 Nexus/Pixel 系列，需要满足三个条件：

  1. 引导加载器已解锁（unlocked bootloader）；
  2. 下载并解压与源码 tag 匹配的厂商闭源二进制（proprietary binaries），自解压脚本会把文件放进 vendor/ 后重新构建；
  3. 有可用的 adb 和 fastboot 工具，并确认设备连接正常。

没有合适真机时，可以用 Cuttlefish 虚拟设备直接运行 main 分支，它不需要厂商闭源库，是云端和 CI 的常用方案。

四、耗材与资源预算

这里的“耗材”指这次投入会被真实消耗掉的资源：磁盘、内存、CPU、网络带宽和时间。预算越清楚，越不容易在同步到一半时卡死。

耗材量级与说明建议
磁盘检出约 250GB，构建再占约 150GB；多分支或多产品还要再加按 400GB 可用起步，用 df -h 盯余量
网络带宽首次同步下载量很大，是否带全量历史影响巨大用 --partial-clone，国内优先镜像源
内存全量构建官方要求 64GB；不足会触发 swap 拖慢构建不要用 swap 代替内存
CPU核数几乎线性决定全量构建时间：6 核约 6 小时，72 核约 40 分钟预算有限时优先核数，其次内存
时间首次同步加首次构建，留出半天到一天中途断网或断电可以重跑，不要放弃
电量与运行成本长时间满负荷构建，笔记本或云主机会持续吃资源云主机按小时计费时，先算清再动手

repo sync 中断后直接重跑即可续传；repo sync <某个项目> 可以只重试失败的项目。网络实在差时降低并发：repo sync -c -j1。

五、下载源码：repo 初始化与同步

安装 repo

最省事的方式是系统包：

sudo apt-get update
sudo apt-get install repo
repo version

官方还提供手动安装方式：从 https://storage.googleapis.com/git-repo-downloads/repo 下载启动器，用公钥 8BB9AD793E8E6153AF0F9A4416530D5E920F5C65 校验后放到 ~/bin/repo。repo version 输出应不低于 2.4。

国内网络如果拉不动默认源，先把启动器镜像指到清华：

export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo

选择分支或 tag

先记住结论： 学习用稳定 tag，追新功能用 main。

官方示例初始化 main 分支：

mkdir aosp-main
cd aosp-main
repo init --partial-clone -b main \
  -u https://android.googlesource.com/platform/manifest

本知识库的例子锁定 Android 14 r75：

repo init --partial-clone -b android-14.0.0_r75 \
  -u https://android.googlesource.com/platform/manifest

-b 指定分支或 tag，-u 指定 manifest 仓库，两者都必不可少。完整 tag 与 build number 对照表见官方“源代码标记和 build”页面。注意：android-14.0.0_r75 是源码 tag，不是手机“设置 → 关于手机”里的系统版本号，两者不要混用。

同步

repo sync -c -j8

-c 表示只取当前分支，减少历史下载；-j8 是并发数。官方口径是“在正常网络下大约需要一小时多一点”，实际取决于带宽、镜像和是否带全量历史。

国内镜像

常用镜像把 manifest 地址整体替换即可，git-repo 启动器地址单独配置：

# 清华镜像
export REPO_URL=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo
repo init --partial-clone -b android-14.0.0_r75 \
  -u https://mirrors.tuna.tsinghua.edu.cn/git/AOSP/platform/manifest

# 中科大镜像
repo init --partial-clone -b android-14.0.0_r75 \
  -u git://mirrors.ustc.edu.cn/aosp/platform/manifest

如果已经用官方源初始化过，重新执行一次带镜像地址的 repo init 即可切换后续同步地址，不需要删除源码。同步遇到 http 403/500 时，优先换镜像或降低并发，而不是反复硬试。

六、构建与运行

标准五步

在源码树根目录执行：

source build/envsetup.sh
lunch aosp_x86_64-eng
m -j$(nproc)
emulator

逐步说明：

  1. source build/envsetup.sh 导入 lunch、m、emulator 等命令。
  2. lunch 选择产品目标。不带参数会列出可选目标列表；官方 AVD 示例用 sdk_phone_x86_64，main 分支的云端示例用 aosp_cf_x86_64_phone-trunk_staging-userdebug。学习用 aosp_x86_64-eng 最省时间。
  3. m 从源码树顶部构建，-j$(nproc) 指定并行任务数；不传 -j 时构建系统会自己选。只想校验构建配置可以 m nothing。
  4. emulator 启动当前构建产物。先确认 /dev/kvm 可用，否则会极慢。

目标名是“产品-发布配置-构建变体”三段式，构建变体三个选项：

变体用途
user生产环境，受限较多
userdebug面向开发，比 user 多了调试能力，真机调试常用
eng构建最快，适合日常开发学习

查看当前目标：echo "$TARGET_PRODUCT-$TARGET_BUILD_VARIANT"。

构建产物在哪里

镜像输出在 out/target/product/<产品名>/，例如 system.img、vendor.img、boot.img。只要源码没动，增量构建只需要几分钟到几十分钟；换产品目标或换 tag 时，输出目录会重建，所以要为 out/ 预留足够磁盘。

模拟器与 Cuttlefish

传统模拟器（AVD）适合本机图形环境；Cuttlefish 适合云端和无头环境。两者产品目标不同：AVD 常用 sdk_phone_x86_64 或 aosp_x86_64-eng，Cuttlefish 用 aosp_cf_x86_64_phone-* 系列。学习阶段选一个即可，不要两个一起折腾。

真机刷机

流程比模拟器多两步：

  1. 到官方二进制下载页下载与源码 tag 匹配的专有二进制，在源码根目录运行自解压脚本，把文件解压到 vendor/，然后重新构建。
  2. 解锁引导加载器后，用 fastboot devices 确认设备，再 fastboot flashall 刷入镜像。

刷机前确认三件事：设备受官方支持、blobs 版本与源码 tag 匹配、bootloader 已解锁。不匹配时设备可能无法开机，先保留原厂镜像以便回退。

七、验证与排障

环境：Linux 终端；网络可访问镜像或官方源；磁盘已预留。

df -h                                        # 磁盘余量
repo version                                 # repo 版本
ls -l /dev/kvm                               # 模拟器加速
echo "$TARGET_PRODUCT-$TARGET_BUILD_VARIANT" # 当前 lunch 目标
adb devices                                  # 真机连接状态
现象优先检查常见原因
repo sync 报 http 403/500换镜像；repo sync -j1官方源不稳定或被网络环境限制
repo init 卡在下载启动器REPO_URL 是否指向 git-repo 镜像默认拉取 Google 源失败
构建被 kill 或极慢内存、swap、-j 并发内存不足，swap 拖垮构建
磁盘写满df -h；清理 out/构建空间预留不足
emulator 起不来或黑屏/dev/kvm、CPU 虚拟化标志无 KVM 或嵌套虚拟化
真机刷完不开机blobs 版本、bootloader 状态版本不匹配或未解锁

常见误区

  1. 只看源码也按全量构建标准配机器：先用 Android Code Search，几乎零成本。
  2. 把 repo 当成 Git 的替代品：repo 是管理多仓库的封装器，底层操作仍然是 Git。
  3. 用手机的系统版本号代替源码 tag：android-14.0.0_r75 是源码快照标识，build number 是产物标识。
  4. 以为所有 Android 手机都能刷 AOSP：只有官方支持设备、解锁引导加载器并配上匹配 blobs 才能跑。
  5. 在 Windows 下“应该也能编译”：官方只支持 glibc Linux，WSL2 属自担风险的方案。
  6. 用大 swap 代替内存：构建会慢到不可用，内存是硬指标。
  7. 把不同 tag 的结论混用：阅读和排障时锁定一个 tag，结论才能复现。

延伸问题

  1. manifest 文件里的 project 和 revision 是什么意思？企业内如何维护定制 manifest？
  2. --partial-clone 少了什么历史？需要完整 git log 时如何补救？
  3. ccache / sccache 如何加速重复构建？
  4. Cuttlefish 与传统 AVD 在镜像格式、启动参数和云端适配上有哪些差异？
  5. out/target/product/<产品名>/ 下的 system.img、vendor.img、boot.img 分别对应哪些分区？

源码入口

文件或目录作用
build/envsetup.sh提供 lunch、m、emulator 等命令
.repo/manifest.xml记录各 Git 项目的位置与 revision
build/make/core/主构建系统与产品规则
device/generic/goldfish/传统模拟器产品定义
device/google/cuttlefish/Cuttlefish 虚拟设备
out/target/product/<产品名>/构建镜像输出目录
AndroidFrameworkGuide | 持续整理 Android Framework 源码与系统开发知识 · 支持本站 · · 苏ICP备2026035779号-2
Copyright © 2026 知晏