现在用 AI Agent 写代码，已经不需要自己死记硬背一整套终端命令了。只要用自然语言跟 Agent 说“帮我提交一下代码”或者“帮我推送到 GitHub”，它就会自动执行对应的命令。
但不用背命令，不代表不需要理解 Git 和 GitHub 背后的概念。如果不清楚它们到底在解决什么问题，你就不知道该在什么时候让 AI 存档、什么时候该拉分支，遇到代码冲突或者密钥泄露时也会手足无措。这篇文章就从零梳理一遍 Git 和 GitHub 的核心机制，以及配合 AI 写代码时最常遇到的几个实际问题。
Git 与 GitHub 的区别：本地存档与云端同步
很多刚接触编程的朋友容易把 Git 和 GitHub 混为一谈：
- Git 是运行在你自己电脑上的命令行版本控制工具。你可以把它理解成单机游戏的本地存档系统——当你用 AI 写好了第一版页面，准备让它继续改第二版时，万一 AI 把原本正常的功能改崩了，只要之前用 Git 存过档，就能随时退回第一版的状态。
- GitHub 是目前最主流的云端代码托管平台（同类的还有 GitLab、Gitee 等）。它相当于游戏的云存档加联机大厅——把本地的 Git 历史同步到 GitHub 上，既能防止换电脑或硬盘损坏导致代码丢失，也能让其他人看到你的项目、下载源码或者一起协作开发。
初始化、提交（Commit）与版本回滚
电脑上装好 Git 之后（可以直接对 AI Agent 说“帮我安装 Git”），它默认并不会监控你电脑里的所有文件夹，否则桌面上的日常文件改动都会被记录下来。
当你新建好一个项目文件夹，需要先对 Agent 说一句：“帮我在这个项目里初始化一下 Git。”这时文件夹下会多出一个隐藏的 .git 目录，代表 Git 开始跟踪这个项目的变动。
需要注意，修改并保存文件，并不等于生成了一个新版本。在写代码的过程中，你可能先后改了十几个文件，只有当你觉得当前功能已经跑通、阶段性告一段落时，才需要告诉 Agent：“帮我提交一下代码（Commit）。”
每次 Commit 都会把当前所有文件的改动打包成一个带编号和说明的版本快照（比如“初始化个人网站”）。如果后续 AI 改乱了代码，你只需要指着某次历史 Commit 对 Agent 说：“帮我回滚到这个版本”，项目就会立刻恢复原状。
分支（Branch）、合并（Merge）与冲突处理
如果一直只在一条主线（默认叫 main 主分支）上改代码，遇到同时尝试两个新功能时就会很麻烦。
假设我们正在做一个个人网站，现在想同时加两个功能：一个是在顶部导航栏加“联系我”按钮，另一个是在同一个导航栏加“深色模式”切换开关。如果把两件事混在一起改，万一“联系我”的逻辑写坏了，整个网站就都没法正常预览，还会把深色模式的代码也搅乱。
更稳妥的做法是使用分支（Branch）。如果把 main 主分支看作树干，我们可以从树干上分出两条独立的树枝：
- 在
branch-a分支上专门开发“联系我”按钮； - 在
branch-b分支上专门开发“深色模式”开关。
两边互不干扰。当 branch-a 里的“联系我”功能测试无误后，我们先告诉 Agent：“把 branch-a 合并（Merge）回 main 主分支。”这时主分支的导航栏右上角就有了“联系我”按钮。
接着我们切到 branch-b，让 Agent 把最新的 main 分支合并过来。这时候就会触发经典的代码冲突（Conflict）：因为 branch-a 和 branch-b 都修改了顶部导航栏同一行的代码，Git 无法自动替你决定“深色模式”按钮应该放在“联系我”的左边还是右边，只能停下来报错。
在 AI 编程工作流里，遇到冲突不需要自己去手动删改冲突标记。直接告诉 Agent：“把主分支合并过来并解决冲突，两个按钮都要保留。”AI 会读懂两边的功能意图并把按钮并排合入；如果你对按钮的先后顺序有偏好，预览后让它调换一下位置即可。
推送到 GitHub 与看懂仓库页面
本地开发跑通后，怎么把代码放到 GitHub 上？
先在 GitHub 网页右上角点击 + 号选择 New repository（新建仓库），填好仓库名称（比如 oil-github）和简介，选择公开（Public，所有人可见，适合开源）或私有（Private，仅自己和受邀协作者可见）。
如果是从头建空仓库，网页上会列出一串标准终端命令（包括 git init、git add 暂存、git commit、git remote add origin 绑定远程地址和 git push 推送）。现在你完全不用手动去敲这几行命令——只要在电脑上给 AI 工具授权好 GitHub 账号（或让 Agent 配置好 GitHub CLI gh），直接把新建仓库的网址发给 Agent，说一句：“把我们项目的代码推送到这个仓库”，它就会自动完成绑定和上传。
打开任何一个 GitHub 仓库主页，最常打交道的是以下几个模块：
README.md：展示在仓库下方的项目说明书，通常包含项目介绍、效果截图和安装运行步骤。Watch/Fork/Star：右上角的三个按钮。Star相当于点赞收藏；Watch是订阅仓库的更新通知；Fork则是把这个开源仓库完整复制一份到你自己的账号下，方便你在别人的基础上做二次开发。Issues：问题与需求讨论区。开源项目的用户遇到 Bug 或想提新功能建议，都会在这里发帖；维护者修好问题后会把对应的 Issue 标为Closed。Pull requests（简称 PR）：合并请求，也是多人协作和代码审查的核心入口。
Pull Request（PR）代码审查与本地同步
刚才我们在本地直接把 branch-a 合并进了主分支；而在团队协作或开源项目里，更规范的做法是通过 Pull Request（PR） 在云端合并。就算是你一个人开发项目，养成提 PR 的习惯也很有帮助。
当我们让 Agent 把还没合并的 branch-b 分支直接推送到 GitHub 后，仓库首页会自动弹出一个黄色提示条，点击 Compare & pull request 就能发起合并请求。
在 PR 页面里，你可以写明这次改动的目的，还可以让系统自动跑一遍单元测试或端到端测试（Checks）。点开顶部的 Files changed 标签页，就能看到这次分支改动与主分支的逐行对比——绿色代表新增代码，红色代表删除代码。
确认代码没问题后，点击页面下方的合并按钮，branch-b 的深色模式功能就正式进入了云端的 main 主分支，随后可以顺手点 Delete branch 删掉已经用完的临时分支。
别忘了，这时候合并发生在 GitHub 云端，你电脑本地的 main 分支还停留在旧状态。回到本地编辑器，对 Agent 说一句：“帮我切回主分支，并拉取（Pull）云端最新的变更”，本地和云端就完全同步了。
实战常踩的三个坑：环境变量、Stash 与 Worktree
搞懂了基本流程，最后聊三个用 AI 写项目时最容易踩坑的实际场景。
1. 用 .gitignore 和 .env 保护隐私密钥
写项目时，文件夹里会有两类绝对不该上传到 GitHub 的东西：一类是体积庞大的第三方依赖包（如 node_modules）或本地大视频文件；另一类是写在 .env 环境变量文件里的数据库密码和各类大模型 API Key。一旦把真实的 .env 推上公开仓库，几分钟内密钥就会被爬虫扫走盗刷。
正确的做法是在项目根目录建一个 .gitignore 文件，把 .env 和 node_modules 写进去，Git 就会自动忽略它们；同时在仓库里放一个 .env.example 示例文件，里面只写变量名、不写具体密钥（例如 AI_API_KEY=），方便别人克隆项目后照着填入自己的 Key。
这里有一个新手常踩的坑：如果你在把 .env 写进 .gitignore 之前，就已经不小心把 .env 提交进 Git 记录里了，那么事后补加 .gitignore 是不会生效的，Git 依然会继续追踪并上传它。遇到这种情况，一定要明确告诉 AI Agent：“帮我把 .env 从 Git 追踪记录里移除，但保留本地文件。”至于项目部署上线时服务器需要的真实密钥，则应该在云服务器或部署平台（如 Vercel）的后台环境变量设置里单独填写。
2. 代码改了一半要切分支：用 Stash 临时暂存
有时你正在某个分支上让 AI 改功能，改到一半还没调通，突然发现主分支上有个紧急小问题要先修。这时候你既不想把半成品代码直接 Commit 成一个脏版本，又不能带着未提交的改动直接切分支。
这时可以直接对 Agent 说：“把我当前没改完的变更先 stash 暂存起来。”Git 会把这批改动临时收进一个隐藏抽屉里，让工作目录恢复干净；等你切去别的分支忙完回来，再让 Agent 把暂存的内容恢复出来继续写即可。
3. 两个 AI Agent 同时并行开发：用 Worktree
现在很多人喜欢同时开两个 Codex 或 Claude 窗口，让两个 Agent 并行开发两个不同的功能分支。但一个本地文件夹同一时间只能切到一个分支，如果你让两个 Agent 在同一个文件夹里各自切分支，两边会互相覆盖代码；而如果直接把整个项目文件夹手动复制粘贴一份，两个文件夹之间的 Git 历史又断开了，后续合并非常麻烦。
解决这个问题的原生工具叫 git worktree（工作树）。你可以直接告诉 Agent：“帮我用 Worktree 为新功能建一个独立的工作目录。”它会在旁边生成第二个文件夹，两个文件夹各自停留在不同的分支上，两个 AI Agent 可以同时在各自的目录里改代码、跑测试，而且底层共享同一套 Git 历史，改完直接合并即可。
使用 Worktree 只需要留意一个细节：新建出来的 Worktree 目录默认只包含受 Git 追踪的代码文件，像刚才提到被 .gitignore 忽略的 .env 密钥文件和 node_modules 依赖包是不会自动拷过去的。因此建好 Worktree 后，记得顺口让 Agent 把 .env 复制过去并装好依赖，两边就能顺畅跑起来了。