说实话在 Windows 10 上拉 Android 源码这件事我一开始是拒绝的。但现实往往由不得你选公司发的笔记本就是 Windows 10虚拟机权限申请不下来双系统又折腾可我又确实需要一份 AOSP 源码来梳理系统架构、改改上层逻辑。折腾了几天把最新 repo 工具、Python 3、Git for Windows 这套组合彻底跑通之后我最大的感受是——这条路完全可行只是坑比想象中多。这篇就把我完整的过程、踩过的坑、以及最终跑通的方案整理出来希望能让后面走这条路的人少翻几次车。这篇内容不挑基础哪怕你第一次接触 Android 源码只要照着步骤来基本也能把源码拉下来。我会尽量把原理讲清楚而不只是丢一串命令给你因为 Windows 环境下真正卡住人的往往不是命令本身而是命令背后那些没人明说的前置条件。1. Windows 下搞 Android 源码为什么总觉得“反人类”很多人第一次尝试在 Windows 上拉 AOSPAndroid Open Source Project源码时都会有一种“这玩意儿根本不是给 Windows 准备的”的感觉。这个感觉没错AOSP 官方文档推荐的是 Ubuntu LTS 环境所有路径、符号链接、大小写敏感、文件权限的设定默认都是按照 Linux 的习惯来的。Windows 文件系统天生跟它有摩擦所以第一步不是急着装工具而是搞清楚摩擦点在哪才能对症下药。1.1 Windows 文件系统的三个天然短板第一个短板是路径长度限制。Android 源码树非常深很多目录一层套一层完整路径动不动就超过 260 个字符而 Windows 传统路径默认就卡在 260 个字符上。你拉取到一半突然冒出一堆“Filename too long”的错误就是这个原因。第二个短板是符号链接支持。AOSP 仓库里大量使用符号链接来复用文件Windows 上如果没有开启开发者模式或者管理员权限Git 创建符号链接时就很容易失败。第三个短板是大小写敏感。Linux 文件系统区分大小写Windows 的 NTFS 默认不区分两个名字只差大小写的文件放进同一个目录在 Windows 上就可能互相覆盖。正是因为这三个短板很多教程一上来就劝你装 WSL 或者虚拟机。这个建议本身没错但并不是所有场景都适用。我这次因为工作环境的限制只能用原生 Windows所以我把重点放在了“最小化摩擦”这件事上——也就是后面要讲的 Git 配置、Python 环境参数、以及 repo 工具的调用方式。1.2 三条路线对比虚拟机、WSL、还是纯 Windows在动手之前我把三条路线认真对比了一遍。虚拟机最稳但代价是至少要预留 100GB 以上的磁盘还要给 VMware 或 VirtualBox 分配足够的内存电脑配置不够的话拉取源码时整个机器都会卡到没法用。WSLWindows Subsystem for Linux是个很好的折中方案文件系统兼容性比原生 Windows 好很多但 WSL 1 和 WSL 2 的磁盘性能差距很大而且如果你公司的 Windows 策略禁止启用 WSL这条路也走不通。我这次选择的是纯 Windows Git Bash Python 3 repo 的方案。优点很明显不用装虚拟机不需要管理员权限改系统功能只要你用的是 Git for Windows 自带的 Bash而不是系统级 WSL而且拉取下来的源码可以直接在 Windows 上阅读和编辑配合 Android Studio 查看代码也方便。缺点也真实存在下载速度受网络环境影响更大部分 repo 命令需要绕开一些 Windows 特有报错。但如果只是“拉源码 阅读源码 简单修改”这个方案完全能打。1.3 工具链清单每一件都有讲究我的最终工具链是这样的Windows 10 企业版 LTSC 2021长期服务版没有商店、没有乱七八糟的预装应用干净Python 3.11.x注意不要用 3.12 以下太老的版本部分依赖包对 Python 版本有要求Git for Windows 最新版自带 Git Bash以及通过 pip 或官方引导脚本安装的 repo 工具。这里多说一句 Python 版本的问题。repo 本身是一个 Python 脚本早期版本还兼容 Python 2现在最新的 repo 已经彻底不兼容 Python 2 了。我在第一次操作时贪快装的是 3.8结果拉取时遇到一些 TLS 相关的问题换了 3.11 之后一切正常。如果你手头还没有 Python直接装 3.11 以上版本别走弯路。2. 环境准备先把“地基”打牢再谈 repo很多人拉源码失败不是因为 repo 不会用而是环境根本就没配置好。这一节我会把 Python、Git、repo 这三样东西的安装和配置细节全部过一遍每一步都会告诉你为什么要这么做。2.1 Python 3 安装两个必须勾选的选项Python 安装本身没什么难度但有两个细节特别容易忽略。第一个是安装首页下方那个“Add Python to PATH”复选框一定要勾上。如果你忘了勾后面在命令行里输入 python 会提示找不到命令虽然可以手动加环境变量但没必要给自己添堵。第二个是选择“Customize installation”进入高级选项时把“Install for all users”选上这样可以避免某些目录权限问题。装完之后不要急着关窗口先打开 Git Bash 输入 python --version 确认一下版本。这里有一个很关键的小细节Windows 10 系统可能会自带一个 Microsoft Store 的 Python 占位符你输入 python 时可能打开的是商店应用。如果出现这种情况在“设置-应用-应用执行别名”里把 python.exe 和 python3.exe 的别名关掉再从命令行调用你手动安装的 Python。2.2 Git for Windows三个配置项决定成败Git for Windows 安装时组件默认全选即可没什么好说的。装完以后真正关键的是配置。第一个必须做的是开启 longpaths 支持git config --global core.longpaths true这个配置让 Git 不再受 260 字符路径限制。第二个是设置 autocrlfgit config --global core.autocrlf falseAOSP 源码里混杂着 LF 和 CRLF 换行符如果让 Git 自动转换换行符拉下来的文件可能被“善意地”改坏编译时会出现一堆莫名其妙的错误。设成 false 的意思是“不要动我的文件内容”从这个项目拉源码的角度看这是最安全的。第三个是配置用户信息git config --global user.name Your Name git config --global user.email your_emailexample.comrepo 在管理多个 Git 仓库时某些操作会用到 user 信息没有的话会直接报错提前配好省一事。2.3 repo 工具的获取最新版和“系统自带版”的差距repo 工具其实只是个 Python 脚本它本身并不包含源码它的作用是管理数百个 Git 仓库的拉取、切换和同步。这里要特别提醒不要用 pip install repo 装到的版本那个版本比较老对最新 Android 分支的支持可能不到位。正确做法是去 Google 官方源码仓库拉取最新的 repo 脚本但考虑到访问便利性也可以通过国内镜像获取。我的做法是直接用 curl 从 googlesource 的镜像地址拉最新版本然后放到一个固定目录。如果你访问官方源不方便也可以找国内维护的 repo 引导脚本。拿到脚本后记得件事在文件开头确认它是 Python 3 版本。旧版 repo 可能还残留着 Python 2 的语法新版第一行通常会写#!/usr/bin/env python3。然后把 repo 文件放到一个目录下比如C:\repo-tool\repo再把这个目录加到系统 PATH。这样你在任何路径下输入 repo 都能执行。添加完成后在 Git Bash 里执行repo --version如果输出了版本号说明 repo 工具已经就位。3. repo 初始化与镜像选择这一步能少走一半弯路环境准备好之后真正的重头戏来了——repo init。这一步看似只是一条命令但里面藏着很多门道尤其是镜像地址的选择直接决定了你后面能不能顺利拉完整个源码树。很多人在这一步就开始卡住其实大多是镜像地址或 manifest 分支没选对。3.1 manifest 仓库源码树的“总清单”repo 的工作原理可以这样理解Android 源码不是一个大仓库而是由几百个独立的 Git 仓库组成的集合。每个仓库都有自己的地址、分支和依赖关系。如果手动一个一个 clone不但繁琐而且容易漏repo 就是来解决这个问题的。repo init 会拉取一个 manifest 仓库这个仓库本身没有实际代码只有一份 XML 清单记录着所有子仓库的地址、路径、分支信息。我生活里类比一下manifest 就像装修图纸repo sync 就是照着图纸一砖一瓦盖楼。所以 repo init 的第一个参数通常指向 manifest 仓库地址第二个参数-b指定分支例如android-13.0.0_r3、android-12.1.0_r5这类版本标签。如果你不确定该选哪个分支可以先从官方分支列表里找或者直接选最新的稳定版本比如 Android 14 或 Android 15 的某个 tag注意 tag 名称一定要写完整写错的话 manifest 拉取不到后面什么都做不了。3.2 镜像地址选择官方源、AOSP 镜像还是国内镜像镜像地址是整个流程里最影响下载速度和成功率的部分。官方源是https://android.googlesource.com/platform/manifest在网络环境理想的情况下最干净但国内用户访问速度时常不理想。替代方案是国内公共镜像比如清华 TUNA 的 AOSP 镜像、中科大镜像等。这些镜像同步 Android 官方仓库使用方式和官方完全一致只是域名不同。以清华镜像为例repo init 可以这样写repo init -u https://mirrors.tuna.tsinghua.edu.cn/git/AOSP/platform/manifest -b android-14.0.0_r15这里要注意一个细节镜像地址最后有没有/platform/manifest、是不是带git路径不同镜像的写法不完全一样建议先去镜像站首页看清楚说明。我见过很多新手因为复制错了路径导致 repo init 拉了半天发现根本不是 manifest 仓库非常浪费时间。3.3 完整初始化命令与常见报错完整的 repo init 流程一般分两步。第一步是初始化第二步是同步。但如果你用的是最新 repoinit 之后不直接 sync而是会提示缺失 CA 证书或者需要配置认证信息。这里有一个常见的报错fatal: unable to access https://.../.git/: SSL certificate problem: unable to get local issuer certificate这个报错在 Windows 上出现的频率很高因为 Windows 的 Git 可能没有正确读取系统证书。临时解决办法是关闭 SSL 验证但我不建议全局关只对特定域名关会更好。不过如果你只是拉取公开的 AOSP 源码其实可以直接用环境变量GIT_SSL_NO_VERIFYtrue跑一次等源码拉下来之后再关掉。这里我提醒一句关验证只适合从可信镜像拉公开代码这种场景自己心里要有数别在不明来源的仓库上也这么干。如果初始化时遇到 repo 提示“Cannot fetch platform/manifest”大概率不是网络问题而是 mirror 地址写错了。去镜像站首页把 manifest 的 git 路径复制完整再重来一次就行。4. 真正拉取源码完整实操过程与核心命令拆解repo init 成功后你就有了一个.repo目录里面存放着 manifest 和后续所有子仓库的元数据。接下来就是最漫长也最容易出问题的环节——repo sync。这一步会耗费大量时间而且对磁盘、内存、网络都有要求所以我会把 sync 命令的参数拆开讲清楚并给出一个适合 Windows 环境的运行方案。4.1 repo sync 参数拆解-j、-c、--no-tags 各是什么含义很多第一次接触 repo sync 的人会直接执行repo sync然后看着屏幕刷屏一等就是几小时。其实 sync 命令有很多参数可以控制拉取方式先理解再动手效率完全不同。最简单的命令是repo sync -c -j4 --no-tags这里的-c表示当前分支只拉取 manifest 指定的分支不拉取所有远程分支能省掉大量不必要的提交记录。-j4表示并发数Windows 环境下我建议不要开太大4 到 8 比较稳。并发数太高会导致网络连接数激增反而容易触发服务器限流而且 Windows 的文件系统并发处理能力不如 Linux开太高容易出奇怪的问题。--no-tags表示不拉取标签AOSP 仓库的标签很多但不一定都用得上去掉能节省时间和磁盘空间。如果你需要冲特定版本做开发--no-tags是可以的。但如果你后续要做版本对比或者精确回溯那建议不要加这个参数宁可多花点时间也别欠下技术债。4.2 断点续传与本地缓存中断不可怕避免从头再来repo sync 最让人崩溃的并不是慢而是拉取到一半突然中断然后你以为下次要重头再来。其实 repo 是支持断点续传的前提是不要手动删除.repo目录也尽量不要在 sync 中途强制结束 Git 进程。当中断发生时直接再次执行同样的 sync 命令即可repo 会比较本地已有对象和远程差异只拉缺失部分。我个人的习惯是每次 sync 前先执行repo sync -c -j4 --no-tags中断后再执行相同的命令。如果连续几次都在同一个仓库处失败可以先单独进入该仓库目录手动执行git fetch排查一下是不是网络或认证问题然后再回到根目录重新 sync。另外一个减少重复劳动的方法是保留.repo目录。很多人拉完源码后觉得.repo占用空间大想删掉。我的建议是不要急着删因为以后切换分支、增量更新都靠它。如果你实在需要空间可以考虑把源码目录压缩归档但.repo尽量留着它就是你整个代码仓库的“本地服务区”。4.3 磁盘占用与空间规划看起来 100GB 够用其实不够Android 源码的体量随着版本增长越来越多这里我给一个大概的参考如果只拉当前分支代码Android 14 的源码加.repo目录总体占用在 80GB 到 120GB 之间。如果你把全部标签和分支都拉下来200GB 都打不住。所以在开始之前先用磁盘管理器检查一下你的目标盘剩余空间我建议至少留 120GB。如果你的磁盘只剩 50GB那就别硬拉了赶紧想办法清空间或者换镜像分支。另外Windows 的文件索引服务、杀毒软件实时扫描都会在拉取大量小文件时拖慢速度。我实测下来把源码目录加入 Windows Defender 的排除列表sync 速度能提升不少。方法是在“病毒和威胁防护-排除项”里添加整个源码目录这不会影响系统安全但对拉取速度提升明显。如果你用的是第三方杀毒软件同样把源码目录加入白名单。4.4 拉取完成后的状态检查拉取完成后不要急着看代码。先在根目录执行repo status如果输出干干净净说明所有仓库都在正确分支上。然后可以随便进入一个子目录比如frameworks/base执行git log --oneline -5看看提交日志是否能正常显示。到这里你的 Windows 原生环境下的 Android 源码就算正式落地了。5. 常见问题与排查技巧实录讲完正常流程再聊聊这次实操里和以往经验中的各种“翻车现场”。有些问题你可能一次都不会遇到但一旦遇到没有排查思路会很崩溃。我把最典型的问题和解决办法整理成了一份速查表也补充了一些独家的排查技巧。5.1 SSL 证书错误与认证问题之前的初始化部分我们提过证书问题这里再展开细说。在 Windows 下Git 默认会使用系统证书库来验证 HTTPS 连接但很多时候系统证书库里缺少某些根证书尤其公司电脑上有安全代理时更容易触发。解决思路有两种一是更新 Git for Windows新版 Git 对证书的处理完善了很多二是临时设置环境变量export GIT_SSL_NO_VERIFYtrue repo sync -c -j4 --no-tagssync 完成之后记得unset GIT_SSL_NO_VERIFY。不过需要说明的是这只是一个临时绕过方案如果你是在内网环境拉取非公开代码建议还是把证书配置好别用这种方式因为安全漏洞非常明显。5.2 文件路径太长导致 checkout 失败这是 Windows 拉 AOSP 时另一个高频问题。明明开启了core.longpaths true但在拉取某些深路径文件时依然报错。我的经验是光设置 Git 配置还不够还需要确保 Windows 系统本身开启了长路径支持。操作方法是可以打开“本地组策略编辑器”在“计算机配置-管理模板-系统-文件系统”中启用“启用 Win32 长路径”。如果你用的是 LTSC 版本这个策略可能存在如果没有也可以直接修改注册表启用。修改完一定要重启电脑否则不生效。如果还是报错可以尝试用管理员的 Git Bash 运行 sync。有些文件写入需要更高权限管理员模式能规避部分权限问题。5.3 repo sync 卡住不动或者一直在 Fetch有时候 sync 执行了很久但看着好像卡住了。这有两种情况一种是在正常拉取大仓库frameworks/base这类超大仓库确实需要较长时间其实没有卡住。另一种是某个远程仓库连接超时repo 会反复重试。我的排查技巧是在 sync 时加上-v参数查看详细输出比如repo sync -c -j4 --no-tags -v如果看到某一个仓库长时间没有进展就 CtrlC 中断单独去.repo/projects/对应路径下执行git fetch手动确认该仓库能否拉取成功。有些时候是仓库地址过期有些时候是本地锁文件残留手动跑一遍能更快定位问题。5.4 恢复拉取默认状态还有一种常见需求是“repo 恢复到拉版本默认状态”——比如你改了很多仓库的代码想回到初始状态重新开始。这时可以用repo forall -c git checkout . git clean -fd这行命令的意思是遍历所有仓库将工作区文件恢复到最近一次提交状态并清理掉未被跟踪的文件。注意git clean -fd是危险操作它会删掉所有未跟踪的文件如果你在某个仓库目录里放了自己的笔记或者脚本也会被一并删除。所以在执行之前最好把源码目录做个备份或者仔细确认没有重要文件。5.5 Git 和 repo 代码仓库管理的优劣势对比顺便回答一个很多人问过的问题直接用 Git 管理多个仓库不行吗为什么要用 repoGit 本身管理单个仓库非常好用但 Android 源码是几百个仓库的集合每个仓库都有独立的历史记录和分支用 Git 手动管理你得写一大堆脚本去循环执行。repo 的本质就是一个仓库管理封装它用 manifest 描述仓库拓扑用一套命令统一操作所有仓库。简单说Git 管单个项目repo 管一群项目。两者不是替代关系而是配合关系——你最终在某个子仓库里操作时用的还是 Git 命令。6. 实操心德真正把 AOSP 用起来的几个建议源码拉下来只是起点怎么把它用好才是关键。最后分享几个我自己在 Windows 环境下使用 AOSP 源码时的习惯都是一些实操中积累出来的经验可能不全面但很实用。第一个建议是不要一上来就用 Android Studio 打开整个源码树。AOSP 工程量巨大Android Studio 直接打开会卡到怀疑人生。正确的做法是先只打开你关心的模块目录比如frameworks/base或者packages/apps/Settings等 Android Studio 建立好索引再逐步扩大范围。如果你有足够的内存也可以生成完整的 IDE 项目文件但那是另外一个复杂话题了。第二个建议是善用repo start来创建新分支。如果你要在某个仓库里改代码不要直接在主分支上改先执行repo start my-dev-branch --all这样会给所有仓库创建一个名为my-dev-branch的新分支。好处是后续编译也好、回退也好都有一个清晰的分支边界。只用 Git 在单个仓库里建分支当然也行但repo start会统一所有仓库的分支名管理起来方便得多。第三个建议是在 Windows 环境下尽量不要去编译整个系统。拉源码、看代码、改上层逻辑都没问题但真正到编译阶段原生 Windows 对 AOSP 的支持依然一般。我的习惯是Windows 上做代码研读和简单修改真正出包还是交给 Linux 服务器。如果你非要在 Windows 上编译那就需要 WSL 或者虚拟机了这又回到开头说的路线选择。第四个建议是给源码目录单独建一个盘符或者分区。因为拉源码过程中会产生大量小文件跨盘操作会很慢而且.repo目录和源码目录如果不在同一分区repo 的硬链接机制会失效磁盘占用会直接翻倍。我自己是把 D 盘整个清空专门拿来放 AOSP空间规划方面一劳永逸。最后再分享一个小技巧Windows 的 Git Bash 对 repo 的支持总体来说不错但偶尔会遇到命令参数解析差异。如果你在命令执行时遇到奇怪的报错可以试试把命令写到.sh脚本里然后用bash 脚本名.sh的方式执行大多数情况下可以绕开解析问题。这个方法帮我解决过好几次看起来“玄学”的报错希望也能帮到你。