1. 为什么在 Windows 上装 repo 会让人抓狂如果你在 Windows 上折腾过 AOSP 或者大型多仓库项目大概率遇到过这个场景照着教程敲下repo init终端直接甩给你一句repo 不是内部或外部命令或者更气人的是命令能跑起来但跑到一半报一堆 Python 语法错误、路径分隔符错误、符号链接创建失败。这不是你操作有问题而是 repo 这个工具从骨子里就是为 Linux 环境设计的它本质上是一个 Python 脚本加上一层 Git 的封装大量依赖 POSIX 路径语义和 shell 行为直接搬到 Windows 上水土不服是常态。这篇内容就是把我自己在 Windows 上反复装 repo、反复踩坑、最后跑通整套流程的经验整理出来。核心要解决的问题很明确在 Windows 环境下让 repo 工具正常可用能够完成 init、sync 这类基础操作。适合两类人看——一类是刚接触多仓库管理、需要在 Windows 上拉取大型项目的新手另一类是之前装过但被各种报错劝退、想搞清楚到底哪一步出了问题的老手。我会把工具选型背后的逻辑、环境变量的配置细节、以及那些文档里不会写的坑一条条拆开讲清楚。先说结论性的判断Windows 上跑 repo主流有两条路一条是走Git Bash Python的原生组合另一条是走WSL。这两条路没有绝对优劣取决于你的项目规模、你对文件系统性能的敏感度、以及你愿不愿意在 Windows 里再养一个 Linux 子系统。下面我会把两条路都讲透重点放在第一条路上因为它的门槛更低、对纯 Windows 用户更友好也是我自己日常用得最多的方案。在正式动手之前有必要先理解 repo 到底是个什么东西否则你装完了也不知道自己在装什么。repo 不是编译器、不是构建工具它就是一个多 Git 仓库的批量管理器。一个大型项目往往由几十上百个独立的 Git 仓库组成手动一个个 clone、一个个切分支、一个个同步工作量巨大且极易出错。repo 的作用就是读一份清单文件manifest按照清单里记录的仓库地址、路径、分支批量帮你完成初始化和同步。它本身是 Google 用 Python 写的一个脚本早期版本对 Python 2 依赖很重现在主流版本已经迁移到 Python 3这也是为什么你的 Windows 上必须有一个能用的 Python 环境。理解了这一点你就能明白为什么安装 repo 的核心其实是三件事让系统能找到 repo 这个可执行入口、让这个入口能调用到正确的 Python 解释器、让 repo 运行时的路径和符号链接行为符合预期。后面所有的步骤和坑基本都围绕这三件事展开。2. 两条技术路线的取舍Git Bash 原生方案 vs WSL 方案2.1 Git Bash 方案的能力边界在哪里Git Bash 是 Git for Windows 自带的一个类 Unix shell 环境它提供了 bash、常见的 coreutils 命令ls、grep、sed、curl 等以及一个精简的 POSIX 兼容层。把 repo 放在 Git Bash 里跑最大的好处是路径语义和 shell 行为接近 Linuxrepo 脚本里那些#!/bin/sh、$(dirname $0)、符号链接操作在 Git Bash 下大多能正常工作。但这个方案有明确的能力边界必须提前说清楚免得你装到一半才发现走不通。第一Git Bash 的 POSIX 兼容层是模拟出来的不是真正的内核级支持某些涉及文件权限位chmod、硬链接、特殊文件类型的操作会静默失败或者行为不一致。第二Git Bash 下的 Python 如果用的是 Windows 原生版 Python那么 Python 内部对路径的处理仍然是 Windows 语义os.symlink这类调用可能因为权限不足而报错。第三性能上Git Bash 的文件系统操作经过一层转换在大仓库 sync 时会比原生 Linux 慢一些但日常使用可以接受。我的实际体验是中小型项目、日常开发、只需要 init 和 sync 的场景Git Bash 方案完全够用配置一次就能长期稳定运行。只有当你的项目规模特别大、或者构建流程里大量依赖 Linux 特有工具链时才需要考虑 WSL。2.2 什么情况下应该直接上 WSLWSL 是在 Windows 里跑一个真正的 Linux 内核子系统repo 在里面运行和在原生 Linux 上几乎没有区别路径、权限、符号链接、shell 行为全部是原生的。如果你符合下面任意一条我建议直接走 WSL不要在 Git Bash 上浪费时间项目构建流程强依赖 Linux 工具链比如需要 gcc、make、各种 Linux 专属的构建脚本仓库数量极多、单次 sync 数据量大对文件系统性能敏感你后续还要在这个环境里跑编译、跑测试而不只是拉代码。WSL 的代价是需要额外安装和配置占用一定的磁盘和内存而且 Windows 和 WSL 之间的文件互访尤其是跨文件系统访问会有性能损耗。一个常见的坑是把项目放在 Windows 的盘符下比如/mnt/c/...然后在 WSL 里操作这样跨文件系统的 IO 会非常慢正确做法是把项目放在 WSL 自己的文件系统里比如~/projects。下面这张表把两条路线的关键差异列清楚你可以对照自己的情况做选择对比维度Git Bash 原生方案WSL 方案安装复杂度低装 Git 和 Python 即可中需要启用 WSL 并安装发行版路径与权限语义模拟部分场景不一致原生 Linux 语义符号链接支持受限需额外配置完整支持大仓库 sync 性能中等高项目放在 WSL 文件系统内与 Windows 工具链协作无缝需要跨系统调用适合场景日常拉取、中小项目大型项目、完整构建我个人的建议是先用 Git Bash 方案跑通如果后续遇到它解决不了的问题再迁移到 WSL。迁移成本其实不高因为 repo 的用法在两边是一样的差别只在环境准备阶段。3. Git Bash 方案的环境准备把地基打牢3.1 Git for Windows 的安装选项里藏着关键开关Git for Windows 是这条路线的基石但很多人在安装时一路点下一步结果漏掉了关键配置。下载安装包后有几个选项必须留意。第一个是默认编辑器的选择。安装向导会让你选 Git 默认使用的编辑器如果你不熟悉 vi/vim建议选一个自己顺手的比如 VS Code 或者 Notepad。这个选项影响的是git commit时打开哪个编辑器写提交信息和 repo 本身关系不大但选错了后续改起来麻烦。第二个也是最关键的是Adjusting your PATH environment这一步。这里有三个选项我强烈建议选中间那个Git from the command line and also from 3rd-party software。这个选项会把 Git 的cmd目录加入系统 PATH使得 Git Bash 里的命令和 Windows 命令行能互相调用。如果你选了最下面的Use Git and optional Unix tools from the Command Prompt会把一堆 Unix 工具塞进系统 PATH可能和 Windows 自带命令冲突选最上面的Use Git from Git Bash only则 Git 命令只能在 Git Bash 里用灵活性差很多。第三个是Configuring the line ending conversions也就是换行符处理。Windows 用 CRLFLinux 用 LF这个选项决定了 Git 如何处理换行符。对于 repo 管理的项目建议选Checkout as-is, commit Unix-style line endings这样检出时保持原样提交时统一转成 LF能避免大量因为换行符导致的假修改。这个设置对跨平台协作的项目尤其重要选错了会导致你明明没改代码git status却显示一堆文件被修改。安装完成后打开 Git Bash敲git --version确认能正常输出版本号地基就算打好了。3.2 Python 环境的版本选择与 PATH 陷阱repo 是 Python 脚本所以 Python 环境是必需品。这里有几个必须讲清楚的细节。版本选择上优先用 Python 3.8 及以上。早期 repo 依赖 Python 2但现在主流版本已经全面转向 Python 3用 Python 2 会直接报语法错误。我实测下来 Python 3.8 到 3.11 都比较稳太新的版本比如 3.12偶尔会遇到某些依赖库还没适配的情况如果你追求稳定选 3.10 或 3.11 是比较保险的区间。安装 Python 时安装向导第一页有个Add Python to PATH的勾选框一定要勾上。这是新手最容易踩的坑不勾的话Python 装完了但系统找不到Git Bash 里敲python提示命令不存在然后你以为是没装成功反复重装。勾上之后安装程序会自动把 Python 的安装目录和 Scripts 目录加入系统 PATH。但即便勾了还有一个隐藏陷阱Windows 自带的应用执行别名会劫持 python 命令。Windows 10/11 默认在设置 应用 应用执行别名里开启了python.exe和python3.exe的别名指向微软商店。当你在命令行敲python时系统可能优先命中这个别名弹出一个商店页面或者报错而不是调用你刚装的 Python。解决办法很简单打开那个设置页面把python.exe和python3.exe两个别名关掉。这个坑我踩过不止一次表现就是明明装了 Python命令行却调不到排查半天才发现是别名在捣乱。装好之后在 Git Bash 里验证python --version python3 --version which python三条命令都应该输出你安装的 Python 版本和路径。如果python和python3指向不一致说明环境里有多个 Python需要理清楚哪个在前。which python的输出路径应该是你安装目录下的而不是 WindowsApps 之类的系统目录。3.3 把 repo 启动器放到 PATH 能找得到的地方repo 的官方分发方式是一个叫repo的 Python 脚本早期还有个repo-launcher的包装。你需要做的是把这个脚本下载下来放到一个在 PATH 里的目录并确保它有可执行权限。具体操作在 Git Bash 里创建一个专门放工具的目录比如~/bin然后把这个目录加入 PATH。下载 repo 脚本可以用 curlmkdir -p ~/bin curl -o ~/bin/repo https://storage.googleapis.com/git-repo-downloads/repo chmod ax ~/bin/repo这里有个细节chmod ax在 Git Bash 下对 Windows 文件系统的作用是有限的它更多是给 Git Bash 的兼容层一个这个文件可执行的标记。真正让repo命令能被找到的是~/bin在 PATH 里。你可以在~/.bashrc里加一行export PATH$HOME/bin:$PATH然后source ~/.bashrc让它生效。验证方式敲which repo应该输出/c/Users/你的用户名/bin/repo这样的路径Git Bash 里 Windows 路径会显示成/c/...的形式。提示如果你所在网络环境访问上面的下载地址不稳定可以换用项目官方文档里给出的其他镜像地址或者手动下载后放到~/bin目录效果一样。4. 让 repo 真正跑起来init 与 sync 的实操链路4.1 第一次 init 前必须想清楚的三件事环境准备好之后很多人迫不及待就敲repo init结果报一堆错。其实 init 之前有三件事必须先确认否则后面全是返工。第一确认你要拉取的项目清单地址manifest URL。repo init 的核心参数就是-u后面跟清单仓库的地址。这个地址决定了你要拉哪个项目的代码不同项目完全不同必须从项目官方文档里拿准确。地址写错的话repo 会报无法访问清单仓库之类的错误。第二确认清单里的分支或标签。用-b参数指定比如-b main或者某个具体的版本标签。不指定的话会用清单仓库的默认分支有时候默认分支是开发分支不一定是你想要的稳定版本。第三确认工作目录。repo 会在当前目录下创建.repo隐藏目录存放管理数据所有仓库会检出到当前目录下。所以一定要先建一个空目录再进去 init不要在已有大量文件的目录里直接 init否则目录结构会乱成一团。一个典型的 init 命令长这样mkdir -p ~/projects/myproject cd ~/projects/myproject repo init -u 清单仓库地址 -b 分支名第一次 init 时repo 会提示你配置 Git 的用户名和邮箱如果之前没配过按提示填就行。它还会问你是否同意某个许可协议输入y继续。4.2 sync 过程中的常见报错与应对init 成功后下一步是repo sync这一步才是真正把几十上百个仓库拉下来的重头戏。这个过程可能持续很久取决于项目规模和网络状况。我整理了几个高频报错和对应的处理思路报错现象可能原因处理思路error: RPC failed; curl 56网络中断或缓冲区不足增大http.postBuffer重试fatal: unable to access ...地址不可达或认证失败检查清单地址、确认凭据配置repo sync卡在某个仓库不动单个仓库过大或网络慢用-j控制并发数或单独 sync 该仓库Permission denied (publickey)SSH 密钥未配置改用 HTTPS 地址或配置密钥符号链接创建失败Windows 权限或文件系统限制开启开发者模式或以管理员运行关于并发数-j默认值往往偏大在网络条件一般的情况下反而容易因为并发过多导致超时。我一般先用repo sync -j4跑稳定后再考虑调大。如果某个仓库反复失败可以用repo sync 仓库路径单独拉取缩小排查范围。还有一个容易被忽略的点sync 中途失败后不要直接删目录重来。repo 支持断点续传重新执行repo sync会跳过已经完成的仓库只补拉失败的。直接删掉.repo重来反而浪费大量时间。4.3 验证安装是否真正可用sync 完成后怎么确认 repo 是真的装好了、而不是看起来能跑我一般做三层验证。第一层repo --version能正常输出版本信息说明脚本本身和 Python 环境没问题。第二层repo info能列出当前项目的清单信息、分支、各仓库状态说明.repo目录结构完整。第三层随便进一个子仓库目录git status和git log能正常工作说明仓库检出完整。三层都过了才算真正可用。只过第一层的话很可能只是脚本能跑但实际 sync 时还会出问题。5. 那些文档里不会写的坑与经验5.1 符号链接Windows 上最隐蔽的拦路虎repo 管理的项目里符号链接symlink用得不少而 Windows 对符号链接的支持是有前提的创建符号链接需要管理员权限或者开启开发者模式。如果你在 sync 过程中看到类似无法创建符号链接的警告或者某些文件明明在清单里却检不出来大概率就是这个原因。解决办法有两个一是以管理员身份运行 Git Bash简单粗暴但每次都要提权不方便二是在 Windows 设置里开启开发者模式设置 更新和安全 开发者选项开启后普通用户也能创建符号链接。我推荐后者一次配置长期有效。还有一个相关的坑Git 本身有个配置core.symlinks在某些 Windows 环境下会被设成false导致 Git 把符号链接当成普通文本文件检出。可以用git config --global core.symlinks true显式打开。改完之后已经检出的仓库需要重新检出才能生效。5.2 路径长度限制与中文路径问题Windows 传统上对路径长度有 260 字符的限制虽然新版本系统可以通过注册表或组策略解除但很多工具链并没有完全适配。repo 管理的项目层级往往很深项目根/.repo/projects/某仓库/...这样的路径很容易超长导致文件创建失败。应对办法把项目放在尽量短的路径下比如C:\proj\或者D:\src\不要放在C:\Users\你的用户名\Documents\各种子目录\...这种深层路径里。另外项目路径里绝对不要出现中文和空格repo 和它调用的各种脚本对非 ASCII 路径的处理并不可靠中文路径导致的诡异报错极难排查。这一条是血泪教训我见过太多人因为路径里有中文排查了一整天。5.3 换行符与文件权限的静默污染前面提过换行符配置这里再强调一次它的实际影响。如果core.autocrlf配置不当你 sync 下来的文件可能全部被转成 CRLF然后git status显示所有文件都被修改实际上你什么都没动。这种假修改会污染你的工作区提交时还可能把无关的换行符变更带进去。建议的全局配置git config --global core.autocrlf input git config --global core.eol lfinput的含义是提交时把 CRLF 转成 LF检出时不转换。配合core.eol lf能最大程度保持和 Linux 环境一致的行为。文件权限方面Windows 没有 Unix 的权限位概念Git 在 Windows 上默认core.filemode false忽略权限变更。这个默认值是对的不要手动改成 true否则会因为权限位差异产生大量假修改。5.4 Python 脚本执行时的编码报错还有一个偶发的坑某些版本的 repo 脚本在 Windows 上执行时会因为默认编码不是 UTF-8 而报UnicodeDecodeError。这是因为 Windows 的 Python 默认用系统区域编码比如 GBK读取文件而 repo 脚本里可能包含非 ASCII 字符。解决办法是设置环境变量强制 Python 用 UTF-8export PYTHONUTF81 export PYTHONIOENCODINGutf-8把这两行加进~/.bashrc能规避大部分编码相关的诡异报错。Python 3.7 及以上支持PYTHONUTF8效果是让 Python 在打开文件时默认使用 UTF-8 编码。6. 从 Git Bash 迁移到 WSL 的平滑路径如果你跑了一段时间发现 Git Bash 方案确实满足不了需求比如项目太大 sync 太慢、或者构建流程强依赖 Linux那么迁移到 WSL 是顺理成章的选择。这里给一条平滑的迁移路径避免推倒重来。第一步在 Windows 里启用 WSL 并安装一个 Linux 发行版具体启用方式参考系统官方文档这里不展开。装好后在 WSL 里重复前面讲的环境准备装 Git、装 Python、下载 repo 脚本、配置 PATH。因为 WSL 是原生 Linux 环境这些步骤比 Git Bash 下更简单很多兼容性问题直接消失。第二步把项目目录放在 WSL 自己的文件系统里比如~/projects/不要放在/mnt/c/下。跨文件系统访问的性能损耗非常明显sync 大仓库时能差出好几倍时间。第三步如果你需要在 Windows 侧访问 WSL 里的文件可以通过\\wsl$\发行版名\home\用户名\...这样的网络路径访问或者用 VS Code 的远程开发功能直接在 WSL 里编辑。这样既享受了 Linux 环境的完整性又保留了 Windows 侧的编辑体验。迁移过程中唯一需要注意的是不要把 Git Bash 下已经 sync 好的.repo目录直接拷到 WSL 里用。两边的路径记录、符号链接、文件权限都不一样拷过去大概率出问题。正确做法是在 WSL 里重新 init 和 sync虽然要重新拉一遍代码但能避免一堆难以排查的兼容性问题。7. 一套可复用的检查清单折腾完这一整套我把关键步骤和检查点整理成一份清单下次换机器或者帮别人配置时直接照着走能省下大量试错时间。环境准备阶段确认 Git for Windows 安装时选了正确的 PATH 选项确认 Python 3.8 已安装且加入了 PATH确认关掉了 Windows 的应用执行别名确认~/bin在 PATH 里且 repo 脚本已放入并有执行标记。配置阶段确认core.autocrlf和core.eol设置正确确认core.symlinks为 true确认开启了开发者模式或准备好提权确认设置了PYTHONUTF8环境变量。实操阶段确认项目路径短且无中文无空格确认 init 前目录为空确认清单地址和分支准确sync 失败时先重试而非删目录用repo --version、repo info、子仓库git status三层验证。这套流程我在不同机器上重复过很多次只要每一步都确认到位Windows 上跑 repo 其实没那么可怕。真正让人崩溃的从来不是工具本身而是那些藏在细节里、文档又不写的环境差异。把地基打牢后面的事情就顺了。 
长河君 · 2026/10/24 7:02:59 · 阅读 1.2k Windows 上安装 repo 的完整指南：Git Bash 与 WSL 方案对比及避坑实践
1. 为什么在 Windows 上装 repo 会让人抓狂如果你在 Windows 上折腾过 AOSP 或者大型多仓库项目大概率遇到过这个场景照着教程敲下repo init终端直接甩给你一句repo 不是内部或外部命令或者更气人的是命令能跑起来但跑到一半报一堆 Python 语法错误、路径分隔符错误、符号链接创建失败。这不是你操作有问题而是 repo 这个工具从骨子里就是为 Linux 环境设计的它本质上是一个 Python 脚本加上一层 Git 的封装大量依赖 POSIX 路径语义和 shell 行为直接搬到 Windows 上水土不服是常态。这篇内容就是把我自己在 Windows 上反复装 repo、反复踩坑、最后跑通整套流程的经验整理出来。核心要解决的问题很明确在 Windows 环境下让 repo 工具正常可用能够完成 init、sync 这类基础操作。适合两类人看——一类是刚接触多仓库管理、需要在 Windows 上拉取大型项目的新手另一类是之前装过但被各种报错劝退、想搞清楚到底哪一步出了问题的老手。我会把工具选型背后的逻辑、环境变量的配置细节、以及那些文档里不会写的坑一条条拆开讲清楚。先说结论性的判断Windows 上跑 repo主流有两条路一条是走Git Bash Python的原生组合另一条是走WSL。这两条路没有绝对优劣取决于你的项目规模、你对文件系统性能的敏感度、以及你愿不愿意在 Windows 里再养一个 Linux 子系统。下面我会把两条路都讲透重点放在第一条路上因为它的门槛更低、对纯 Windows 用户更友好也是我自己日常用得最多的方案。在正式动手之前有必要先理解 repo 到底是个什么东西否则你装完了也不知道自己在装什么。repo 不是编译器、不是构建工具它就是一个多 Git 仓库的批量管理器。一个大型项目往往由几十上百个独立的 Git 仓库组成手动一个个 clone、一个个切分支、一个个同步工作量巨大且极易出错。repo 的作用就是读一份清单文件manifest按照清单里记录的仓库地址、路径、分支批量帮你完成初始化和同步。它本身是 Google 用 Python 写的一个脚本早期版本对 Python 2 依赖很重现在主流版本已经迁移到 Python 3这也是为什么你的 Windows 上必须有一个能用的 Python 环境。理解了这一点你就能明白为什么安装 repo 的核心其实是三件事让系统能找到 repo 这个可执行入口、让这个入口能调用到正确的 Python 解释器、让 repo 运行时的路径和符号链接行为符合预期。后面所有的步骤和坑基本都围绕这三件事展开。2. 两条技术路线的取舍Git Bash 原生方案 vs WSL 方案2.1 Git Bash 方案的能力边界在哪里Git Bash 是 Git for Windows 自带的一个类 Unix shell 环境它提供了 bash、常见的 coreutils 命令ls、grep、sed、curl 等以及一个精简的 POSIX 兼容层。把 repo 放在 Git Bash 里跑最大的好处是路径语义和 shell 行为接近 Linuxrepo 脚本里那些#!/bin/sh、$(dirname $0)、符号链接操作在 Git Bash 下大多能正常工作。但这个方案有明确的能力边界必须提前说清楚免得你装到一半才发现走不通。第一Git Bash 的 POSIX 兼容层是模拟出来的不是真正的内核级支持某些涉及文件权限位chmod、硬链接、特殊文件类型的操作会静默失败或者行为不一致。第二Git Bash 下的 Python 如果用的是 Windows 原生版 Python那么 Python 内部对路径的处理仍然是 Windows 语义os.symlink这类调用可能因为权限不足而报错。第三性能上Git Bash 的文件系统操作经过一层转换在大仓库 sync 时会比原生 Linux 慢一些但日常使用可以接受。我的实际体验是中小型项目、日常开发、只需要 init 和 sync 的场景Git Bash 方案完全够用配置一次就能长期稳定运行。只有当你的项目规模特别大、或者构建流程里大量依赖 Linux 特有工具链时才需要考虑 WSL。2.2 什么情况下应该直接上 WSLWSL 是在 Windows 里跑一个真正的 Linux 内核子系统repo 在里面运行和在原生 Linux 上几乎没有区别路径、权限、符号链接、shell 行为全部是原生的。如果你符合下面任意一条我建议直接走 WSL不要在 Git Bash 上浪费时间项目构建流程强依赖 Linux 工具链比如需要 gcc、make、各种 Linux 专属的构建脚本仓库数量极多、单次 sync 数据量大对文件系统性能敏感你后续还要在这个环境里跑编译、跑测试而不只是拉代码。WSL 的代价是需要额外安装和配置占用一定的磁盘和内存而且 Windows 和 WSL 之间的文件互访尤其是跨文件系统访问会有性能损耗。一个常见的坑是把项目放在 Windows 的盘符下比如/mnt/c/...然后在 WSL 里操作这样跨文件系统的 IO 会非常慢正确做法是把项目放在 WSL 自己的文件系统里比如~/projects。下面这张表把两条路线的关键差异列清楚你可以对照自己的情况做选择对比维度Git Bash 原生方案WSL 方案安装复杂度低装 Git 和 Python 即可中需要启用 WSL 并安装发行版路径与权限语义模拟部分场景不一致原生 Linux 语义符号链接支持受限需额外配置完整支持大仓库 sync 性能中等高项目放在 WSL 文件系统内与 Windows 工具链协作无缝需要跨系统调用适合场景日常拉取、中小项目大型项目、完整构建我个人的建议是先用 Git Bash 方案跑通如果后续遇到它解决不了的问题再迁移到 WSL。迁移成本其实不高因为 repo 的用法在两边是一样的差别只在环境准备阶段。3. Git Bash 方案的环境准备把地基打牢3.1 Git for Windows 的安装选项里藏着关键开关Git for Windows 是这条路线的基石但很多人在安装时一路点下一步结果漏掉了关键配置。下载安装包后有几个选项必须留意。第一个是默认编辑器的选择。安装向导会让你选 Git 默认使用的编辑器如果你不熟悉 vi/vim建议选一个自己顺手的比如 VS Code 或者 Notepad。这个选项影响的是git commit时打开哪个编辑器写提交信息和 repo 本身关系不大但选错了后续改起来麻烦。第二个也是最关键的是Adjusting your PATH environment这一步。这里有三个选项我强烈建议选中间那个Git from the command line and also from 3rd-party software。这个选项会把 Git 的cmd目录加入系统 PATH使得 Git Bash 里的命令和 Windows 命令行能互相调用。如果你选了最下面的Use Git and optional Unix tools from the Command Prompt会把一堆 Unix 工具塞进系统 PATH可能和 Windows 自带命令冲突选最上面的Use Git from Git Bash only则 Git 命令只能在 Git Bash 里用灵活性差很多。第三个是Configuring the line ending conversions也就是换行符处理。Windows 用 CRLFLinux 用 LF这个选项决定了 Git 如何处理换行符。对于 repo 管理的项目建议选Checkout as-is, commit Unix-style line endings这样检出时保持原样提交时统一转成 LF能避免大量因为换行符导致的假修改。这个设置对跨平台协作的项目尤其重要选错了会导致你明明没改代码git status却显示一堆文件被修改。安装完成后打开 Git Bash敲git --version确认能正常输出版本号地基就算打好了。3.2 Python 环境的版本选择与 PATH 陷阱repo 是 Python 脚本所以 Python 环境是必需品。这里有几个必须讲清楚的细节。版本选择上优先用 Python 3.8 及以上。早期 repo 依赖 Python 2但现在主流版本已经全面转向 Python 3用 Python 2 会直接报语法错误。我实测下来 Python 3.8 到 3.11 都比较稳太新的版本比如 3.12偶尔会遇到某些依赖库还没适配的情况如果你追求稳定选 3.10 或 3.11 是比较保险的区间。安装 Python 时安装向导第一页有个Add Python to PATH的勾选框一定要勾上。这是新手最容易踩的坑不勾的话Python 装完了但系统找不到Git Bash 里敲python提示命令不存在然后你以为是没装成功反复重装。勾上之后安装程序会自动把 Python 的安装目录和 Scripts 目录加入系统 PATH。但即便勾了还有一个隐藏陷阱Windows 自带的应用执行别名会劫持 python 命令。Windows 10/11 默认在设置 应用 应用执行别名里开启了python.exe和python3.exe的别名指向微软商店。当你在命令行敲python时系统可能优先命中这个别名弹出一个商店页面或者报错而不是调用你刚装的 Python。解决办法很简单打开那个设置页面把python.exe和python3.exe两个别名关掉。这个坑我踩过不止一次表现就是明明装了 Python命令行却调不到排查半天才发现是别名在捣乱。装好之后在 Git Bash 里验证python --version python3 --version which python三条命令都应该输出你安装的 Python 版本和路径。如果python和python3指向不一致说明环境里有多个 Python需要理清楚哪个在前。which python的输出路径应该是你安装目录下的而不是 WindowsApps 之类的系统目录。3.3 把 repo 启动器放到 PATH 能找得到的地方repo 的官方分发方式是一个叫repo的 Python 脚本早期还有个repo-launcher的包装。你需要做的是把这个脚本下载下来放到一个在 PATH 里的目录并确保它有可执行权限。具体操作在 Git Bash 里创建一个专门放工具的目录比如~/bin然后把这个目录加入 PATH。下载 repo 脚本可以用 curlmkdir -p ~/bin curl -o ~/bin/repo https://storage.googleapis.com/git-repo-downloads/repo chmod ax ~/bin/repo这里有个细节chmod ax在 Git Bash 下对 Windows 文件系统的作用是有限的它更多是给 Git Bash 的兼容层一个这个文件可执行的标记。真正让repo命令能被找到的是~/bin在 PATH 里。你可以在~/.bashrc里加一行export PATH$HOME/bin:$PATH然后source ~/.bashrc让它生效。验证方式敲which repo应该输出/c/Users/你的用户名/bin/repo这样的路径Git Bash 里 Windows 路径会显示成/c/...的形式。提示如果你所在网络环境访问上面的下载地址不稳定可以换用项目官方文档里给出的其他镜像地址或者手动下载后放到~/bin目录效果一样。4. 让 repo 真正跑起来init 与 sync 的实操链路4.1 第一次 init 前必须想清楚的三件事环境准备好之后很多人迫不及待就敲repo init结果报一堆错。其实 init 之前有三件事必须先确认否则后面全是返工。第一确认你要拉取的项目清单地址manifest URL。repo init 的核心参数就是-u后面跟清单仓库的地址。这个地址决定了你要拉哪个项目的代码不同项目完全不同必须从项目官方文档里拿准确。地址写错的话repo 会报无法访问清单仓库之类的错误。第二确认清单里的分支或标签。用-b参数指定比如-b main或者某个具体的版本标签。不指定的话会用清单仓库的默认分支有时候默认分支是开发分支不一定是你想要的稳定版本。第三确认工作目录。repo 会在当前目录下创建.repo隐藏目录存放管理数据所有仓库会检出到当前目录下。所以一定要先建一个空目录再进去 init不要在已有大量文件的目录里直接 init否则目录结构会乱成一团。一个典型的 init 命令长这样mkdir -p ~/projects/myproject cd ~/projects/myproject repo init -u 清单仓库地址 -b 分支名第一次 init 时repo 会提示你配置 Git 的用户名和邮箱如果之前没配过按提示填就行。它还会问你是否同意某个许可协议输入y继续。4.2 sync 过程中的常见报错与应对init 成功后下一步是repo sync这一步才是真正把几十上百个仓库拉下来的重头戏。这个过程可能持续很久取决于项目规模和网络状况。我整理了几个高频报错和对应的处理思路报错现象可能原因处理思路error: RPC failed; curl 56网络中断或缓冲区不足增大http.postBuffer重试fatal: unable to access ...地址不可达或认证失败检查清单地址、确认凭据配置repo sync卡在某个仓库不动单个仓库过大或网络慢用-j控制并发数或单独 sync 该仓库Permission denied (publickey)SSH 密钥未配置改用 HTTPS 地址或配置密钥符号链接创建失败Windows 权限或文件系统限制开启开发者模式或以管理员运行关于并发数-j默认值往往偏大在网络条件一般的情况下反而容易因为并发过多导致超时。我一般先用repo sync -j4跑稳定后再考虑调大。如果某个仓库反复失败可以用repo sync 仓库路径单独拉取缩小排查范围。还有一个容易被忽略的点sync 中途失败后不要直接删目录重来。repo 支持断点续传重新执行repo sync会跳过已经完成的仓库只补拉失败的。直接删掉.repo重来反而浪费大量时间。4.3 验证安装是否真正可用sync 完成后怎么确认 repo 是真的装好了、而不是看起来能跑我一般做三层验证。第一层repo --version能正常输出版本信息说明脚本本身和 Python 环境没问题。第二层repo info能列出当前项目的清单信息、分支、各仓库状态说明.repo目录结构完整。第三层随便进一个子仓库目录git status和git log能正常工作说明仓库检出完整。三层都过了才算真正可用。只过第一层的话很可能只是脚本能跑但实际 sync 时还会出问题。5. 那些文档里不会写的坑与经验5.1 符号链接Windows 上最隐蔽的拦路虎repo 管理的项目里符号链接symlink用得不少而 Windows 对符号链接的支持是有前提的创建符号链接需要管理员权限或者开启开发者模式。如果你在 sync 过程中看到类似无法创建符号链接的警告或者某些文件明明在清单里却检不出来大概率就是这个原因。解决办法有两个一是以管理员身份运行 Git Bash简单粗暴但每次都要提权不方便二是在 Windows 设置里开启开发者模式设置 更新和安全 开发者选项开启后普通用户也能创建符号链接。我推荐后者一次配置长期有效。还有一个相关的坑Git 本身有个配置core.symlinks在某些 Windows 环境下会被设成false导致 Git 把符号链接当成普通文本文件检出。可以用git config --global core.symlinks true显式打开。改完之后已经检出的仓库需要重新检出才能生效。5.2 路径长度限制与中文路径问题Windows 传统上对路径长度有 260 字符的限制虽然新版本系统可以通过注册表或组策略解除但很多工具链并没有完全适配。repo 管理的项目层级往往很深项目根/.repo/projects/某仓库/...这样的路径很容易超长导致文件创建失败。应对办法把项目放在尽量短的路径下比如C:\proj\或者D:\src\不要放在C:\Users\你的用户名\Documents\各种子目录\...这种深层路径里。另外项目路径里绝对不要出现中文和空格repo 和它调用的各种脚本对非 ASCII 路径的处理并不可靠中文路径导致的诡异报错极难排查。这一条是血泪教训我见过太多人因为路径里有中文排查了一整天。5.3 换行符与文件权限的静默污染前面提过换行符配置这里再强调一次它的实际影响。如果core.autocrlf配置不当你 sync 下来的文件可能全部被转成 CRLF然后git status显示所有文件都被修改实际上你什么都没动。这种假修改会污染你的工作区提交时还可能把无关的换行符变更带进去。建议的全局配置git config --global core.autocrlf input git config --global core.eol lfinput的含义是提交时把 CRLF 转成 LF检出时不转换。配合core.eol lf能最大程度保持和 Linux 环境一致的行为。文件权限方面Windows 没有 Unix 的权限位概念Git 在 Windows 上默认core.filemode false忽略权限变更。这个默认值是对的不要手动改成 true否则会因为权限位差异产生大量假修改。5.4 Python 脚本执行时的编码报错还有一个偶发的坑某些版本的 repo 脚本在 Windows 上执行时会因为默认编码不是 UTF-8 而报UnicodeDecodeError。这是因为 Windows 的 Python 默认用系统区域编码比如 GBK读取文件而 repo 脚本里可能包含非 ASCII 字符。解决办法是设置环境变量强制 Python 用 UTF-8export PYTHONUTF81 export PYTHONIOENCODINGutf-8把这两行加进~/.bashrc能规避大部分编码相关的诡异报错。Python 3.7 及以上支持PYTHONUTF8效果是让 Python 在打开文件时默认使用 UTF-8 编码。6. 从 Git Bash 迁移到 WSL 的平滑路径如果你跑了一段时间发现 Git Bash 方案确实满足不了需求比如项目太大 sync 太慢、或者构建流程强依赖 Linux那么迁移到 WSL 是顺理成章的选择。这里给一条平滑的迁移路径避免推倒重来。第一步在 Windows 里启用 WSL 并安装一个 Linux 发行版具体启用方式参考系统官方文档这里不展开。装好后在 WSL 里重复前面讲的环境准备装 Git、装 Python、下载 repo 脚本、配置 PATH。因为 WSL 是原生 Linux 环境这些步骤比 Git Bash 下更简单很多兼容性问题直接消失。第二步把项目目录放在 WSL 自己的文件系统里比如~/projects/不要放在/mnt/c/下。跨文件系统访问的性能损耗非常明显sync 大仓库时能差出好几倍时间。第三步如果你需要在 Windows 侧访问 WSL 里的文件可以通过\\wsl$\发行版名\home\用户名\...这样的网络路径访问或者用 VS Code 的远程开发功能直接在 WSL 里编辑。这样既享受了 Linux 环境的完整性又保留了 Windows 侧的编辑体验。迁移过程中唯一需要注意的是不要把 Git Bash 下已经 sync 好的.repo目录直接拷到 WSL 里用。两边的路径记录、符号链接、文件权限都不一样拷过去大概率出问题。正确做法是在 WSL 里重新 init 和 sync虽然要重新拉一遍代码但能避免一堆难以排查的兼容性问题。7. 一套可复用的检查清单折腾完这一整套我把关键步骤和检查点整理成一份清单下次换机器或者帮别人配置时直接照着走能省下大量试错时间。环境准备阶段确认 Git for Windows 安装时选了正确的 PATH 选项确认 Python 3.8 已安装且加入了 PATH确认关掉了 Windows 的应用执行别名确认~/bin在 PATH 里且 repo 脚本已放入并有执行标记。配置阶段确认core.autocrlf和core.eol设置正确确认core.symlinks为 true确认开启了开发者模式或准备好提权确认设置了PYTHONUTF8环境变量。实操阶段确认项目路径短且无中文无空格确认 init 前目录为空确认清单地址和分支准确sync 失败时先重试而非删目录用repo --version、repo info、子仓库git status三层验证。这套流程我在不同机器上重复过很多次只要每一步都确认到位Windows 上跑 repo 其实没那么可怕。真正让人崩溃的从来不是工具本身而是那些藏在细节里、文档又不写的环境差异。把地基打牢后面的事情就顺了。