刘炳琦上月初有个朋友抱着一台 Windows 笔记本找我，他那个 Android 项目已经写了一个多月，某天晚上改 UI 布局越改越乱，想回到三个小时前还能编译通过的版本，结果翻遍了桌面和网盘，只有一堆“最终版”“最终版2”“打死不改版”的文件夹。他说自己早就想用 Git 做版本管理，但每次搜教程看到一堆命令行就头大，加上 GitHub 在本地网络环境里时不时超时，就一拖再拖。这个场景我太熟悉了——很多 Windows 下的 Android 开发者不是不想用版本控制，而是卡在了初始配置和远程仓库连不上这两道坎上。
这篇文章我打算把完整链路讲清楚：从 Windows 上安装配置 Git，到 Android Studio 4.0.0 里把一个项目纳入版本管理，再推到 GitHub，最后再讲清楚为什么我后来把主力仓库换成了码云 Gitee，以及切换时最容易踩的坑。不管是刚入门想给自己写的 App 加个保险，还是跟我一样被 GitHub 的访问速度折磨过、想迁移到 Gitee 的开发者，这篇文章应该都能帮你少走几趟弯路。
1. Windows 下先把 Git 跑起来：环境配置和两个直接影响后续体验的选项
很多人以为装了 Android Studio 就能直接用 Git，这个理解不准确。Android Studio 自带的版本控制功能只是一个图形化前端，真正干活的是安装在系统里的 Git 程序。Android Studio 会去系统 PATH 里找 git.exe，找不到就会在 VCS 菜单里报错。所以第一步永远是：给 Windows 装一个 Git。
1.1 安装 Git 时不要一路默认，这两个选项决定你后面要不要加班
Git 的 Windows 版安装包叫 Git for Windows，官方地址下载很慢的话，可以用国内高校镜像或者直接搜“Git for Windows 国内下载”，这类资源比较好找。安装过程大部分步骤确实可以直接点 Next，但有两个选项我建议你留意。
第一个是安装路径。默认装到 C:\Program Files\Git 没问题，但如果你习惯把开发工具放到非 C 盘，注意路径里别带中文和空格，不然后面某些脚本工具找 Git 时会莫名奇妙报错。第二个是 Adjusting your PATH environment 这一步，一定要选第二项：
code复制Git from the command line and also from 3rd-party software
这个选项的意思是：把 Git 的 cmd 目录加入系统 PATH，这样不仅 CMD 和 PowerShell 里能直接敲 git 命令，Android Studio 这类第三方软件也能通过 PATH 自动发现 Git。如果选了第一项（仅 Git Bash 使用），Git Bash 里能跑 git 命令，但 Android Studio 很可能无法自动识别 Git 路径，还得手动去设置里填，凭空多一步操作。
装完之后，打开 CMD 或 PowerShell 验证一下：
bash复制git --version
能输出版本号就说明装好了。如果提示“git 不是内部或外部命令”，多半是 PATH 没生效，重启终端或者注销重登一次再试。
1.2 用户信息和换行符：不配好这两个东西，提交记录和代码对比都会很难看
Git 装好之后，第一件事是配置用户名和邮箱。很多人忽略这一步，结果第一次 commit 时 Git 报错，或者在 GitHub 上显示的提交人是一串“你的主机名”，团队协作时根本不知道谁提交的。
打开终端，执行：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
--global 表示对当前 Windows 用户下的所有 Git 仓库生效。邮箱建议用你 GitHub/Gitee 注册时填的那个，这样提交记录能自动关联到账号头像。
第二个配置是 Windows 用户特别容易踩的换行符问题。Windows 文本文件默认用 CRLF 换行，而 Linux/macOS 用 LF。Git 为了跨平台协作，默认会在提交时把 CRLF 转成 LF，检出时再转回 CRLF。但如果你在 Windows 上开发，项目里又混有 shell 脚本等必须用 LF 的文件，没有统一配置就会出现“整个文件都被标记为已修改”的恐怖现象。
我个人的做法是配置成：
bash复制git config --global core.autocrlf true
这样 Windows 下提交会自动转 LF，检出转 CRLF。如果你的项目里有 .sh 脚本或者 Docker 构建文件，可以在项目根目录加一个 .gitattributes 强制指定这些文件用 LF，两个文件一配合，基本可以告别换行符噩梦。
顺手再配置一个后面防乱码要用的参数：
bash复制git config --global core.quotepath false
这个先记下来，第五章会详细讲它是怎么解决中文文件名乱码的。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Android Studio 4.0.0 启用版本控制：从零到第一次提交的完整路径
环境里的 Git 装好以后，接下来就是在 Android Studio 里把一个项目变成一个 Git 仓库。4.0.0 这个版本的界面比较传统，菜单栏还保留着经典的 VCS 入口，和后来 Arctic Fox 那些版本换了 UI 不太一样，但这套操作逻辑其实是通用的。
2.1 先别急着把文件交给 Git，把忽略规则写好再说
打开你的 Android 项目，顶部菜单找到 VCS -> Enable Version Control Integration，弹窗里选择 Git，点 OK。这时候 Android Studio 右下角会提示项目已被纳入 Git 管理，文件树里的文件名也会开始显示颜色：红色表示未跟踪，绿色表示新增，蓝色表示修改过。看到红绿蓝，说明版本控制生效了。
接下来很重要的一步：写 .gitignore。Android Studio 新建项目时一般会自动生成根目录的 .gitignore 和 app 模块下的 .gitignore，但如果你是从老版本迁移过来的项目，或者不小心选错了模板，可能没有这些文件。我习惯自己检查一遍，确保这些内容在忽略列表里：
gitignore复制.gradle/
build/
local.properties
.idea/
*.iml
.DS_Store
/captures
.externalNativeBuild
.cxx
每一行为什么要忽略，我简单说下。.gradle/ 和 build/ 是构建产物，占了仓库体积的大头，提交它们只会让仓库越来越臃肿，别人拉下来还得重新构建，完全没有意义。local.properties 里面记录的是你本机 SDK 的绝对路径，每台电脑都不一样，提交之后反而会导致别人 sync 时报错。.idea/ 是 IDE 的个人配置目录，里面的 workspace.xml 包含你打开的窗口、运行配置等私有信息，团队协作时这些内容互相覆盖非常痛苦。*.iml 是模块配置文件，同理属于个人级文件。
如果你的项目里已经误提交了这些文件，先不要慌，后面第五章有清理方法。但还没提交的话，现在写对 .gitignore 就是最优解。
2.2 第一次 commit：提交信息怎么写才不至于三个月后看不懂
忽略规则配好之后，右键点击项目根目录，选择 Git -> Add，把当前所有文件加入暂存区。然后菜单栏 VCS -> Commit，也可以直接用快捷键 Ctrl + K，Android Studio 会弹出 Commit 面板，里面能看到待提交的文件列表和差异对比。
第一次提交信息我建议简单直接，比如：
code复制feat: 初始化项目，完成基础模块搭建
很多人不重视提交信息，随手写一个“111”“update”，过两个月自己回来看历史记录时完全想不起来每次提交干了什么。推荐用 Conventional Commits 的简化版，格式是 类型: 描述，常见的类型有：
feat：新功能fix：修 Bugrefactor：重构，不涉及功能变化docs：文档相关style：格式调整，不影响逻辑test：测试相关
好处是以后用 git log --oneline 看历史时，每个提交的目的一目了然，回滚时也能快速定位到“到底改了什么才导致的这个 Bug”。这个习惯越早养成，后面受益越大。
Commit 完成后，项目右键菜单里选 Git -> Repository -> Log 或者按 Alt + 9 打开 Git 工具窗口，能看到这条提交记录，本地仓库就算正式建起来了。
3. 和 GitHub 握手：SSH 配置、远程仓库创建与 push 全链路
本地仓库只能给自己后悔药吃，真正方便的是把代码托管到 GitHub。这样换电脑、发版本、和别人协作都从容很多。这一章我会把远程连接配置的细节讲透，尤其是 HTTPS 和 SSH 的选择问题，这直接决定了你后面会不会被密码反复折磨。
3.1 为什么我强烈建议用 SSH 而不是 HTTPS：一次配置，永久免密
连接 GitHub 有两种主流方式。HTTPS 方式在 clone 仓库时要用 https://github.com/xxx/xxx.git 这样的地址，每次 push 都要输一次 GitHub 用户名和密码，虽然 Windows 凭据管理器会记住一部分，但遇到凭据失效或账号换掉的时候，报错信息能让你怀疑人生。SSH 方式则是在本地生成一对密钥，把公钥放到 GitHub 上，之后所有 Git 操作都走加密通道，不再需要输密码。
我把两者的差异整理成一张表，方便你根据自己情况选：
| 对比维度 | HTTPS | SSH |
|---|---|---|
| 首次配置 | 零配置，clone 直接用 | 需要生成密钥并配置公钥 |
| 日常使用 | 可能频繁输密码或处理凭据 | 永久免密 |
| 安全性 | 传输加密，但凭据保管是隐患 | 非对称加密，私钥不出本地 |
| 网络失败概率 | 国内网络下相对更容易超时 | 相对更稳定一点 |
| 适合场景 | 临时使用、只读 clone | 长期开发、高频 push |
我自己的项目全部走 SSH。刚开始确实会觉得生成密钥有点麻烦，但这个一次性的成本非常值得。别人还在为每几次 push 弹出来的登录框烦恼时，你已经在安静地提交了。
生成密钥的步骤如下。打开 Git Bash 或者 PowerShell，执行：
bash复制ssh-keygen -t rsa -b 4096 -C "你的邮箱"
一路回车，默认会在 C:\Users\你的用户名\.ssh\ 下生成 id_rsa（私钥）和 id_rsa.pub（公钥）两个文件。公钥是给人看的，可以随便分享；私钥千万别泄露，谁拿到它谁就能操作你的仓库。
然后用记事本打开 id_rsa.pub，复制全部内容。登录 GitHub，右上角头像 -> Settings -> SSH and GPG keys -> New SSH key，标题随便填，把公钥粘贴进去保存即可。
Windows 下还需要确认 ssh-agent 服务在运行。按 Win + R，输入 services.msc，找到 OpenSSH Authentication Agent，如果状态不是“正在运行”，右键启动，并把启动类型改成“自动”。这一步不做的话，有时候 Git 会提示找不到你的密钥，但其实密钥文件就在那里。
最后验证一下：
bash复制ssh -T git@github.com
如果看到 Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access. 说明 SSH 已经通了，可以正式和 GitHub 对话了。
3.2 在 GitHub 创建远程仓库并完成首次 push：理解 origin 和默认分支
在 GitHub 网页上点击左上角 New 新建仓库，仓库名建议和 Android Studio 项目名保持一致，公开还是私有按自己需要选。不需要勾选“Add a README file”，因为我们本地已经有代码，避免产生不必要的冲突。
建好仓库之后，你会看到一个包含命令提示的页面。如果你的仓库是空的，可以直接用 Android Studio 里的图形化操作：VCS -> Import into Version Control -> Share Project on GitHub，输入仓库名和描述，Android Studio 会自动帮你创建远程仓库并 push 代码。不过这个功能依赖内置的 GitHub 插件，有时候会卡在授权弹窗上，所以我更推荐用命令行方式来理解整个过程。
在 Android Studio 底部打开 Terminal，执行：
bash复制git remote add origin git@github.com:你的用户名/仓库名.git
这里 origin 是远程仓库的默认别名，约定俗成代表“主要的远程仓库”。Git 允许一个本地仓库关联多个远程仓库，你可以给它们起不同的名字，比如有人会留一个 github、一个 gitee，这在双托管场景下很实用。
添加完远程地址后 push：
bash复制git push -u origin master
-u 的意思是设置上游跟踪，以后直接敲 git push 就能推送到这个分支。这里有一个分支名的坑：Android Studio 4.0.0 时代 git init 默认创建的分支名是 master，但 GitHub 新建仓库默认主分支名已经改成了 main。如果你的 GitHub 仓库是用网页新建并初始化的，它可能是 main，而你本地是 master，push 时可能会提示分支跟踪失败。
解决办法是把本地分支重命名为 main 再推：
bash复制git branch -M main
git push -u origin main
如果仓库是先在 GitHub 上空建、再由你本地第一次 push 的，那用 master 还是 main 都无所谓，只要两边对应上就行。我建议统一改成 main，因为这是 GitHub 现在的主流命名，团队协作时少一点认知负担。
4. 从 GitHub 改成 Gitee：切换托管平台的三种姿势和 clone 报错排查
这一章是标题的另一个重点：为什么要迁到 Gitee，以及怎么迁最稳妥。我说下自己的真实感受：GitHub 在国内网络环境下访问确实不稳定，commit 推一半卡住、网页加载半天打不开的情况我遇到太多次了。Gitee 作为国内平台，服务器在国内，clone 和 push 的速度几乎是秒开。加上 Gitee 的私有仓库是免费的，很多团队和我一样把它当主力仓库，GitHub 反而变成了一个“海外备份”。
4.1 三种迁移姿势：手工改地址、镜像导入、双远端并存
第一种方式最简单，适合本地代码是最新状态、只是想换个托管平台的情况。在 Gitee 上新建一个空仓库，然后回到本地项目目录，修改远程仓库地址：
bash复制git remote set-url origin git@gitee.com:你的用户名/仓库名.git
这个命令不会删除本地历史，也不会动代码文件，只是把远程仓库的地址改掉。改完直接：
bash复制git push -u origin master
本地所有提交历史、分支会一次性推到 Gitee，效果和原来 GitHub 上的一模一样。我推荐大多数人用这种方式，干净、直接、可控。
第二种方式适合想把 GitHub 上的整个仓库内容——包括 Issue、PR、Wiki——都搬过来的情况。Gitee 提供了“从 GitHub 导入仓库”的功能，在 Gitee 首页右上角 + -> 从 GitHub 导入仓库，填上你 GitHub 仓库的完整地址，Gitee 会自动拉取。如果仓库是私有的，需要在 GitHub 上生成一个只读的 Access Token 填进去，Gitee 才有权限读取。整个过程是全自动的，导入完就是一个独立的新仓库，之后和 GitHub 那边的更新就不再同步了。
第三种方式是双托管，适合暂时不想完全放弃 GitHub 的人。类似这样配置：
bash复制git remote add gitee git@gitee.com:你的用户名/仓库名.git
git remote add github git@github.com:你的用户名/仓库名.git
以后每次要推两个平台，就执行：
bash复制git push gitee master
git push github master
或者更省事一点，把 push 默认行为改成同时推多个地址，但这需要对 git 配置有一定了解，对新手来说先手动推两个也不费事。我个人极度推荐第一种方式：本地一个 origin 指向 Gitee，简单不混乱。双托管看着灵活，实际上日常很容易忘推某一个，等到真需要从另一个平台拉代码时才发现两边已经分叉，反而更麻烦。
4.2 clone 报错 “git did not exit cleanly (code 128)”：根因定位与解决
在 Android Studio 里通过 File -> New -> Project from Version Control 输入 Gitee 仓库地址时，很多人会遇到这个经典报错。对话框弹出一句“git did not exit cleanly (code 128)”，具体原因却被藏起来了，很坑。
我踩过几次之后总结出三个排查方向。
第一，远程仓库地址是否正确。检查你粘贴的地址是不是 git@gitee.com:用户名/仓库名.git 这种 SSH 格式，或者 https://gitee.com/用户名/仓库名.git 这种 HTTPS 格式。很多人会把 HTTPS 页面的地址复制到 SSH 配置里，或者反过来，格式不匹配直接 128。另外确认仓库名拼写、用户名大小写，这些错一个字符都是这个报错。
第二，Windows 凭据管理器里的旧账号残留。如果你之前用 HTTPS 方式 clone 过同一个仓库，而 Git 账号后来换过，Windows 凭据管理器会存着旧密码，导致 Git 用旧凭据去访问，被服务器拒绝。解决办法是：控制面板 -> 凭据管理器 -> Windows 凭据，找到 git:https://gitee.com 或 git:https://github.com 开头的条目，删除，然后重新 push 或 clone，会弹出新的登录框去输入正确账号。
第三，SSH 密钥没有添加到 Gitee。如果地址用的 SSH 格式，但 Gitee 账号下没配置过公钥，Git 会直接拒绝连接。Gitee 的配置入口在：头像 -> 设置 -> 安全设置 -> SSH 公钥，把 id_rsa.pub 的内容粘进去保存。验证方式：
bash复制ssh -T git@gitee.com
能显示“Hello 你的用户名”之类的提示就通了。这里有个特别方便的点：同一把本机生成的 SSH 公钥，可以同时添加到 GitHub 和 Gitee，两边都能免密使用，不用单独再生成一次。
如果做了以上三步还报错，建议在 Terminal 里直接跑一次 git clone，终端里的错误信息往往比 Android Studio 弹窗详细得多，能直接看到是权限问题、网络问题还是仓库不存在。命令行永远是排查 Git 问题最直接的入口。
4.3 Gitee 与 GitHub 的操作一致性：会一个就会另一个
迁到 Gitee 之后，你可能会担心操作习惯是不是要重新学一遍。实际上完全不必要。Git 本身是同一个工具，Gitee 和 GitHub 提供的是 Git 托管服务，它们只是服务器端的管理界面和功能权限有一些差异。日常开发中你用的 git add、git commit、git push、git pull、分支切换、代码合并，在两端没有任何区别。Gitee 有 Android Studio 插件吗？其实不需要，Android Studio 内置的 Git 支持是通用的，只要远程地址填对，Gitee 的仓库和 GitHub 的仓库对它来说只是两个不同的 URL。唯一需要注意的可能是 Gitee 网页端的一些中文界面和权限选项位置跟 GitHub 不太一样，但这些不影响 Git 操作本身。
5. Windows 上那些没写在官方文档里的坑：乱码、仓库膨胀、日常操作习惯
最后这一章，我把自己在 Windows 环境下用 Android Studio 做 Git 管理时踩过的零碎坑集中说一下。这些坑官方文档大多不会写，但实际开发中非常高频。
5.1 中文乱码：文件名变八进制、提交信息变成问号，根源在这里
Windows 中文环境下遇到 Git 乱码概率很高，表现形式有两种。
第一种是文件名乱码。执行 git status 时，中文文件名的文件显示成 "\346\265\213\350\257\225.txt" 这样的八进制转义。这个不是文件真的坏了，而是 Git 默认对非 ASCII 文件名做了转义处理。解决方法是第一节就让你配好的：
bash复制git config --global core.quotepath false
配置完再执行 git status，中文文件名就能正常显示了。
第二种是提交信息乱码。如果你在 CMD 里敲中文提交信息，提交后 git log 看到的是乱码，这通常是终端编码问题——Windows 默认代码页是 GBK，而 Git 内部和 GitHub/Gitee 都默认 UTF-8。解决思路是让终端和 Git 的编码一致，都走 UTF-8。
在 Windows 10 及以上系统里，最简单的办法是打开终端后先执行：
bash复制chcp 65001
把当前终端代码页切到 UTF-8。如果你用的是 Android Studio 内置的 Terminal，还可以在 File -> Settings -> Editor -> File Encodings 里把 IDE 编码、项目编码、属性文件编码全部设为 UTF-8，这样在 Android Studio 里直接写提交信息就不会乱。另外，你在 git commit -m "中文信息" 时报错或不显示，可以先确认一下 Git for Windows 安装时是否勾选了 “Use UTF-8 in Git Bash”，不过这个选项只影响 Git Bash，对 CMD/PowerShell 影响不大，最通用的做法还是统一终端编码。
5.2 仓库越用越卡、.git 体积膨胀：问题多半出在误提交的构建产物上
有段时间我的项目 .git 目录涨到 2GB 多，push 一次要等老半天。排查后发现是最早没写 .gitignore 时，把一大堆 build/ 目录里的编译产物提交进去了，这些文件每次构建都会变，Git 就会把它当成新版本存一份，久而久之仓库体积失控。
如果你已经误提交了构建产物，清理思路是这样的：先把它们从 Git 索引中移除，但保留本地文件：
bash复制git rm -r --cached build/
git rm -r --cached .gradle/
git rm --cached local.properties
改好 .gitignore 之后，再提交一次，然后执行：
bash复制git commit -m "chore: 移除误提交的构建产物"
git gc
git gc 会清理 Git 对象数据库里的冗余对象，能回收一部分空间。但要注意，git gc 只能处理当前已经没有引用指向的旧对象，只要旧提交还在历史里，那些构建产物仍会躺在历史提交中占用空间。要让仓库彻底瘦身，需要用 git filter-branch 或 BFG 这类工具重写历史。我建议普通项目不要轻易重写历史，尤其是已经多人协作的仓库——重写历史相当于把所有提交记录重来一遍，协作的人全部要重新克隆，代价很高。一个更稳妥的做法是：从现在开始写对 .gitignore，同时偶尔用 git gc --prune=now 做一下常规维护就够了。要是误提交了大文件（比如动辄几百 MB 的 APK），那确实得考虑 BFG 或者 Git LFS，但 Android 源代码项目里通常不该出现这种文件，最好的策略还是预防。
5.3 日常开发里我建议形成的几个 Git 操作习惯
版本管理工具装上只是第一步，真正让它发挥价值的是日常使用习惯。我用 Git 这么多年，最建议大家养成下面这几个习惯。
提交要尽量小、尽量频繁。一个功能模块写完、一个 Bug 修完，就可以提交一次。不要憋到下班前一次性把几十个文件全塞进一个 commit 里，那样以后回滚根本不知道回滚到什么程度。每次提交一个清晰的主题，配合写清楚的提交信息，就是给未来的自己留线索。
pull 之前先处理本地的状态。如果你的工作区有未提交的改动，直接 git pull 很可能产生冲突，或者 Git 会拒绝拉取。习惯是：pull 之前先 commit 或 git stash 暂存，拉完再处理。Android Studio 里也可以在 VCS -> Update Project 时选择策略，但干净的工作区永远是最省心的。
多利用图形化对比工具。Android Studio 的 VCS -> Git -> Compare with Branch、Show History 这些功能非常强大，能直观地看到每个文件在某些提交之间改了什么。刚开始不敢用命令行的人，完全可以从这些可视化操作入手，等理解了 Git 的数据模型，再回去看命令行反而会更有感觉。
最后再分享一个实际项目中的小经验。我现在的常规操作是：本地开发时每隔一小段时间就 commit 一次，功能稳定后 push 到 Gitee。Gitee 是主力托管平台，速度快、私有仓库免费，偶尔需要给 GitHub 上的人分享时，再用双远端配置把代码推到 GitHub 那边。Windows 环境下这套组合比单一依赖 GitHub 要省心得多。第一次配 SSH、写 .gitignore 这些准备工作可能也就花二十分钟，但之后每天省下的时间、减少的焦虑，远远不止这二十分钟。如果你现在还在用文件夹复制粘贴做备份，我真心建议你今天就花二十分钟把这条链路搭起来。