企业官网建设流程全解析

上礼拜同事扔给我一台装了 Windows 10 Enterprise LTSC 2021 的机器，说想拉一份 Android 源码下来研究系统启动流程，问我是不是非得装 Ubuntu。我说不用，Windows 10 原生环境配 Python 3 也能把 repo 这套工具链跑通，只是比 Linux 用户多填几个坑。

这篇文章就是我把这套流程完整走了一遍之后整理出来的。内容面向想在 Windows 10 下通过 Python 3 和最新版 repo 工具下载 Android 源码的人。不管你是想做 ROM、研究 framework 层代码，还是只想把某一条 branch 拉下来查提交历史，下面这些步骤、命令和坑位基本都能直接套用。

1. 先把repo工具是什么掰开揉碎

1.1 repo不是下载器，是"项目群管理器"

很多人刚接触 Android 源码时以为 repo 是一个类似迅雷的下载工具，这个理解其实不太对。AOSP 不是单个 Git 仓库，而是由几百个 Git 仓库组成的大项目，比如 framework/base、build/make、packages/apps/Settings 这些各自独立。如果一个个去git clone，不仅命令多，版本还容易对不上。

repo 要做的事情，是读取一份 manifest 清单文件，里面记录了 AOSP 某个版本到底由哪些 Git 仓库、哪些 commit 组成，然后按清单统一执行 git 命令。所以更准确地说，repo 是"管 Git 仓库群的经理"，它自己不会发明下载逻辑，底层调用的仍然是 Git。

1.2 最新repo为什么非要Python 3

repo 本身用 Python 写的。早期版本还兼容 Python 2.7，所以你在网上会看到一大批老教程让用户先装 Python 2。但这类教程现在已经过时了，最新官方 repo 代码已经彻底放弃 Python 2，并且运行版本要求至少是 Python 3.8 以上。

如果你机器上同时装了 Python 2 和 Python 3，或者用了特别老的 repo 脚本，运行时会直接抛SyntaxError: invalid syntax，严重一点连repo --help都跑不出来。Windows 10 下正确的做法是只保留 Python 3，并且把它加到 PATH 里，其他版本能卸就卸。

1.3 Windows 10拉Android源码的难点不在Python，在环境差异

真正让 Windows 用户头疼的往往不是 Python，而是下面的基础环境差异：

• AOSP 仓库里存在符号链接（symlink），Windows 原生文件系统默认不友好。
• 很多路径非常长，Windows 老版本默认只支持 260 个字符的路径限制。
• Git 在 Windows 上默认可能把换行符转成 CRLF，导致源码出现大量假差异。
• repo 内部大量使用 POSIX 风格的命令，在 CMD 和 PowerShell 里跑很容易翻车。

解决这些问题的核心思路是：用Git Bash作为操作 shell，用 python.org 官方的 Python 3，配一个干净无中文的源码目录，再加上一点全局 Git 配置。下面逐个来。

2. Windows 10环境准备：把坑提前填平

2.1 Python 3安装时的一个关键选项

去 python.org 下载当前稳定的 Python 3.x 安装包，比如 3.11 或 3.12。安装第一步，务必勾选最底部的Add Python 3.x to PATH，这一步不勾，后面全是坑。

安装完打开 Git Bash 验证：

python --version

如果显示类似Python 3.12.1就说明没问题。但这时候再试一下：

python3 --version

大概率会报command not found。原因很常见：Windows 的 Python 官方安装包默认不会生成python3.exe，而最新 repo 脚本的 shebang 写的是#!/usr/bin/env python3。也就是说，即使你 Python 装好了，Git Bash 里也可能找不到python3这个命令。

解决办法是在~/.bashrc里加一行别名：

echo "alias python3='python'" >> ~/.bashrc source ~/.bashrc

然后再执行python3 --version就没问题了。这一步很多教程不提，但实际跑 repo 时卡住的人有不少就是倒在这里。

提示：不建议使用 Microsoft Store 版本 Python，也不建议从各种"一键环境包"里蹭 Python。repo 这个工具对标准库依赖不多，但对基础解释器的干净程度有要求，官方安装包最省心。

2.2 Git for Windows的安装选项与全局配置

Git 是 repo 的底层执行者，必须装。安装 Git for Windows 时，在 “Adjusting your PATH environment” 这一步选择默认的 “Git from the command line and also from 3rd-party software”，这样 Git Bash、CMD、Python 脚本都能找到 git。

接下来是关键部分，line ending 选项建议选Checkout as-is, commit as-is。如果选了 Windows 风格的自动转换 CRLF，AOSP 这种规模的项目会在 checkout 时产生海量换行符差异，严重拖慢速度，甚至导致 Git 误判文件冲突。

装完后在 Git Bash 里执行：

git config --global core.autocrlf false git config --global core.fileMode false git config --global core.symlinks true

这三行分别表示：不要自动转换换行符、不要比对文件可执行权限位、允许创建符号链接。前两个能避免很多无意义的 status 变化，第三个是 AOSP 仓库能否正常 checkout 的关键。

2.3 开启开发者模式，让符号链接真正可用

AOSP 源码里确实存在 symlink，Windows 上 Git 默认不一定能创建。Windows 10 从 1703 版本开始提供开发者模式，开启后普通用户进程也可以创建符号链接，不需要额外提权。

开启方式：按 Win 键，输入ms-settings:developers回车，然后把“开发人员模式”开关打开。或者在 Git Bash 里跑：

start ms-settings:developers

开启后重启一次 Git Bash，确保配置生效。

2.4 下载repo脚本的正确姿势

从官方渠道下载 repo 脚本到C:\tools：

mkdir -p /c/tools cd /c/tools curl -o repo https://storage.googleapis.com/git-repo-downloads/repo

这里有个细节：下载完不要用 Windows 自带记事本去修改或另存这个文件。记事本默认编码是 UTF-8 with BOM，会在文件开头插入不可见字符，导致 Git Bash 解析 shebang 时报\ufeff相关错误。如果非要用编辑器查看，推荐 VS Code 或 Notepad++，并保持 UTF-8 without BOM。

然后把/c/tools加入 PATH，并确认python3别名已经生效：

export PATH=$PATH:/c/tools repo --help

第一次运行repo --help时，repo 会自动从远端仓库拉取完整的 repo 运行框架，存到用户目录下的隐藏配置里，所以会比想象中慢一点。看到类似usage: repo的帮助信息，就说明基础环境已经通了。

3. repo init：选错分支和路径会白等两小时

3.1 目录规划：纯英文、顶层目录、磁盘要够大

AOSP 目录名千万不要带中文，也尽量别带空格。比如D:\源码\Android 16这种路径，在 Git Bash、Python、Git 三者之间传输时，极容易因为编码不一致而报看不懂的错。我自己踩过UnicodeEncodeError的坑，排查了半天最后发现就是路径里的中文导致的。

推荐直接用一个顶层目录：

mkdir -p /d/aosp cd /d/aosp

磁盘空间一定要提前看。Android 14 这种规模的源码，单纯 checkout + 完整 Git 对象，轻松超过 120GB，我建议剩余空间至少留 150GB，后面还要给编译或其他工具留余量。

3.2 初始化前的Git身份

repo 在拉取和同步过程中会调用 git，Git 的 user.name 和 user.email 必须提前配好，否则某些 commit 操作会报错：

git config --global user.name "Your Name" git config --global user.email "you@example.com"

这里的名字和邮箱不需要真实，但格式必须合法。老手经常忽略这一步，结果 repo 跑到一半报Please tell me who you are，然后一脸懵。

3.3 选稳定分支，别默认main

执行 init 时，最常见的问题是很多人不指定-b参数，直接拉默认分支。AOSP 的默认分支是持续变化的主干开发版，目录结构可能随时调整，而且数据量比稳定分支大得多。对于绝大多数人来说，应选择已经冻结发布的稳定 tag。

例如想拉 Android 14 对应的源码：

repo init -u https://android.googlesource.com/platform/manifest -b android-14.0.0_r1

具体 tag 以官方 release 页面为准。如果你不确定某个 tag 是否存在，可以先去 manifest 仓库的分支列表里确认，不要自己猜，否则 init 会报分支找不到，白白浪费时间。

提示：如果你所在网络访问 Google 源不稳定，这不是 Windows 或 Python 的代码问题。可以考虑把你的 manifest URL 和 REPO_URL 指向一个你确认网络可达的仓库地址或公司内网缓存，不要在同一个源上反复 init。反复重试只会留下半截状态，后面更难排查。

3.4 第一次init的完整命令

在D:\aosp目录里执行：

repo init -u https://android.googlesource.com/platform/manifest -b android-14.0.0_r1

看到类似repo has been initialized in /d/aosp的提示，说明 init 成功。此时目录里会出现一个.repo隐藏文件夹，真正的源码还没有下载，里面只是 manifest 和 repo 管理数据。如果 init 阶段就报错，先回看 PATH、python3 别名和网络这三个点。

4. repo sync：下载全流程与我的调参经验

4.1 用-c只拉当前分支，磁盘和速度都友好

很多第一次跑 repo sync 的人会直接执行repo sync，这会把 manifest 中所有仓库的所有远程分支都拉下来。AOSP 有些仓库历史非常庞大，全量同步的体量会比预期多出好几倍。

我推荐这样做：

repo sync -c -j4 -f

参数含义：

• -c：只同步 manifest 指定的那个分支，不拉所有远程分支。
• -j4：同时启动 4 个下载任务。不要一上来就-j16，Windows 下进程数太多容易把内存吃满，也容易触发不明不白的失败。
• -f：某个仓库失败时不要中断整个同步，先把能拉的拉完，最后再看失败项。

如果你第一次 sync 是用-j16跑到一半挂掉的，不要慌，重新跑上面的命令即可。Git 的对象传输是增量的，已经下载的部分不会被重复下载。

4.2 给Git减负，防止内存和压缩带来的奇怪问题

Windows 下经常出现的失败是index-pack died或者Out of memory之类的报错。这通常不是 repo 的问题，而是 Git 在做对象解压缩和打包时占用资源过多。

如果反复出现这类报错，可以在同步前做一次全局配置：

git config --global core.compression 1 git config --global pack.windowMemory 256m git config --global pack.threads 1

core.compression 1降低压缩等级，减少压缩耗时；pack.windowMemory限制 Git 打包时的内存上限；pack.threads 1让 Git 不强撑多线程。这样会牺牲一点点速度，但稳定性明显提升。不是所有机器都需要这一步，只有遇到反复同步失败时再开。

4.3 给Windows Defender加排除目录，速度立竿见影

这是 Windows 用户才有的烦恼。Windows 自带的 Defender 实时防护会在 Git 创建大量新文件时反复扫描，AOSP 几十万个文件，这个开销非常可观。我实测过：不排除之前，repo sync在 checkout 阶段能卡到让人怀疑人生；排除之后明显顺畅很多。

以管理员身份打开 PowerShell，执行：

Add-MpPreference -ExclusionPath "D:\aosp"

注意路径和你实际的源码目录保持一致。如果已经跑过部分同步但中途失败，加完排除后建议删掉.repo重新 init 再 sync，避免旧状态和性能环境不匹配。

4.4 同步完成的判断标准

repo sync 全部跑完时，终端会回到 shell 提示符，并且最后一段没有fatal error或ERROR。你可以在源码根目录看到art/、build/、frameworks/、packages/等顶层目录。

这时候可以随便挑一个目录验证：

cd frameworks/base git log --oneline -3

能正常输出提交记录，说明这个仓库已经完整检出了。不要只看目录存在就认为成功，有些仓库可能因为网络中断而只拉了一半，用git log验证是最直接的。

5. 我在Windows 10下repo sync时遇到的五个高频坑

5.1 明明装了Python，却提示找不到python3

最典型的场景是：Python 装好了，python --version正常，但运行 repo 时报/usr/bin/env: 'python3': No such file or directory。

原因前面说过，官方 Windows Python 不生成python3.exe。解决方式就是在~/.bashrc里加alias python3='python'。如果你还是想在 CMD 里跑，可以手动把python.exe复制一份改叫python3.exe，但 Git Bash 方案更顺滑。

5.2 用记事本编辑过repo文件后，报奇奇怪怪的语法错误

\ufeff是一个隐藏的 BOM 字符，记事本保存会把#!/usr/bin/env python3变成带 BOM 的 shebang。Git Bash 在解析时会把\ufeff当作未知命令的一部分，报错信息里经常会有一个看起来像空白但又不是空白的字符。

遇到这种问题，不要试图手动删除，直接重新下载一份干净的 repo 文件覆盖即可。

5.3 HTTPS证书报错

错误信息往往长这样：

fatal: unable to access '...': SSL certificate problem: unable to get local issuer certificate

这通常和 Git 的证书存储有关，尤其是在老版本 Git for Windows 上，CA 根证书可能没有完整同步到系统证书库。建议先把 Git for Windows 升级到新版本，新版本自带了更完整的证书链。不要用GIT_SSL_NO_VERIFY=true这种绕过证书校验的应急操作，源码里的提交历史涉及大量可信内容，关掉校验后你无法确认下载来源是否可靠。

5.4 symlink无法创建，checkout直接失败

如果你没有提前开启开发者模式，或者 Git 的core.symlinks是 false，sync 到某些包含符号链接的仓库时会失败，错误信息里通常带着symlink或unable to create symbolic link字样。

正确顺序是：先开启 Windows 10 开发者模式，再执行git config --global core.symlinks true，最后删掉之前下载失败的源码目录重新 init。在坏掉的工作区上打补丁不是不行，但状态很容易越补越乱。

5.5 下载了很久才发现磁盘不够

AOSP 源码体积太大，初学者很容易忽略磁盘容量。一个信号是 sync 到某个仓库时一直卡在 checkout 阶段，或者系统提示磁盘写满。在 Git Bash 里可以用df -h .查看当前目录所在磁盘的剩余空间。

已经在半路发现磁盘不够时，别硬扛，先清理出足够空间，再重新跑repo sync -c -j4。如果连压缩对象都写不进去，可以加-f跳过部分大仓库，先保证主要代码到位，但这种做法只适合应急看代码。

下面把高频问题整理成一张速查表：

6. 源码拉下来之后：Windows能做什么，不能做什么

6.1 用IDE和搜索工具读代码完全可行

下载完成后，Windows 原生环境用来读代码、搜代码、查提交历史完全没问题。我常用的组合是 VS Code 配合全局搜索，或者用 Source Insight 看 framework 层 Java 代码。AOSP 自带 idegen 工具，也可以生成 Android Studio 可导入的android.ipr，但导入之后只能当代码浏览器用，别指望它能像普通 App 工程那样直接编译。

6.2 想在Windows上编译AOSP：别硬来

AOSP 官方支持的编译环境是 Linux 和 macOS，Windows 原生环境并不在支持列表里。就算你用 Python 把源码下载到了 Windows，也不要尝试直接跑make或lunch，结果通常是一堆 shell 脚本和符号链接层面的报错。WSL2 可以作为一种折中，但正确做法是把源码放在 WSL2 的 ext4 文件系统里重新拉取，而不是去挂载 NTFS 目录编译，后者速度慢到无法忍受。

如果你最终目标是编译一个可刷机的镜像，我的建议很直接：在 Linux 云主机、本地 Linux 机器或 WSL2 里直接从 sync 开始做，不要觉得 Windows 已经把源码拉下来了就能省这一步。

6.3 一个更省时间的组合拳

我自己现在的习惯是两步走：Windows 只负责拉源码和阅读，绝不碰编译；需要构建时，在 Linux 环境里用同样一份 manifest 重新拉一遍。不要觉得这样浪费磁盘，编译产物动辄几十 GB，把 Windows 和 Linux 的工作目录混在一起，最后调试起来只会更痛苦。

最后再分享一个经验：如果你只是想把源码下载下来看代码，那么repo sync -c -j4 -f是最舒服的组合，磁盘占用小、失败不影响大局、断点续传也方便。关键是前期的 Python 3、Git Bash、开发者模式、长路径这几个环境点一定提前配好，否则后面任何一个报错都可能让你误以为是网络问题，白白浪费一整天。