!10-git-collaboration_index.png (../../public/images/Advanced/10-git-collaboration_index.png)
第十章：Git 版本控制与跨平台协作
序言
功能越来越丰富，你的本地 Git 仓库里已经积累了厚厚一摞存档记录。一天，你的好朋友也打算跟你一起做。
你可能以为一个人就能搞定。实际情况是：一个人往往精力分散，而 2-3 人小团队——有人负责前端界面，有人负责后端接口，有人负责写测试——反而跑得更快。Git 协作的核心，就是让每个人专注自己的领域，同时保持代码同步。
现在，为了让朋友能拿到你的代码，老师傅告诉你，你需要把这些本地的存档同步到云端。
云端仓库与认证
他向你介绍了代码托管平台（如 GitHub 或国内的 Gitee）。 协作的本质其实很简单：你已经在自己的电脑上通过 AI 养成了良好的提交习惯（第二章提到的本地 Commit），现在只需要多一步操作。
SSH认证：老师傅推荐 SSH认证更安全方便，生成密钥对后，不需要每次输入密码。本章节会详细讲解 SSH 原理和配置步骤。
在开始推代码之前，你需要在 GitHub 上注册一个账号。注册很简单，但在终端里登录往往是新手的第一道坎。 当你第一次运行 git push 时，终端会要求你提供凭证。老师傅特意叮嘱：
- 不要输入你的 GitHub 登录密码：现在 GitHub 早就禁用了密码登录终端。
- 使用 Access Token (令牌)：你需要去 GitHub 网页设置里生成一个令牌（Token），把它当成密码填进去。
- 或者更推荐 SSH 方式：生成一对 SSH 密钥（公钥给 GitHub，私钥留给自己），这样每次推送代码都不用输密码，既安全又方便。
- 本地凭证存储：如果你使用 HTTPS 方式（输入账号密码/令牌），Git 通常会贴心地把你的凭证存在系统的"凭证管理器"里，这样你也不用每次都手动输入。
认证通过后，流程就通顺了：
git push(推)：把你的本地存档记录上传到云端仓库。git pull(拉)：你的朋友在另一头，把云端的最新进度下载到他的电脑上。
这比互相发压缩包要靠谱得多，因为 Git 能够精准地记录每一行代码是谁在什么时候修改的。
跨平台协作
然而，当你的 Windows 电脑遇到朋友的 Mac 电脑时，你踩到了三个经典的跨平台协作大坑。
一：.gitignore
在第六章，我们为了安全配置了 .gitignore。在协作阶段，这个文件有了新的意义：防止污染队友的环境。 如果你不小心把 node_modules 上传了，你的朋友拉取代码时会下载成千上万个并不适配他电脑系统的依赖包，导致项目直接跑不起来。 老师傅让你在 Push 之前，再次确认：依赖包（node_modules）和密钥（.env）绝对不能出现在云端仓库和Git 提交历史里。
二：跨平台兼容
你的项目在朋友的 Mac 上报错说"找不到文件"。你明明写的是 import Button from './button'，文件名叫 Button.tsx，在你的 Windows 电脑上跑得欢快无比。
老师傅告诉你，不同操作系统之间有几个容易忽略的差异：
- 系统垃圾文件：Windows 会自动生成
Thumbs.db，Mac 会生成.DS_Store，这些都是系统文件，不应该出现在项目里。把它们加到.gitignore就可以了。 - 文件名大小写：Windows 不区分大小写（
Button.js和button.js被视为同一个文件），但 Mac/Linux 会区分。建议统一用小写命名文件，避免麻烦。 - 换行符差异：不同系统用的换行符不一样，不过现在的 Git 和编辑器都能自动处理，一般不用手动操心。
配置好这些，跨平台协作就顺畅多了。
三：路径分隔符
作为 Windows 用户，你还踩了一个隐形的坑。你直接从文件资源管理器复制的路径包含反斜杠 \，例如 src\components\Button。这在代码中会被识别为转义字符，导致报错。而 Linux/Mac 系统使用的是正斜杠 /。因此，在编写代码引用路径时，永远手动使用正斜杠 /。Node.js 等现代工具会自动处理它在不同系统下的兼容性。
配置完这些，你和小伙伴的协作就顺畅多了。每次改完代码，记得按顺序执行：git add . → git commit -m "描述" → git push。小伙伴那边用 git pull 就能拿到你的最新修改了。
自动化 Git 工作流
不过，老师傅提醒你，这个"标准三件套"是给人类手动操作准备的。既然你在用 AI 编程，完全可以把它交给 AI：
"每次完成功能或修复 Bug 后，自动执行 git add、git commit（带中文描述）和 git push。"
这样你完全不需要记住这些命令，AI 会在合适的时机自动帮你处理。
查看历史与差异
有时候你想看看"AI 到底改了什么"或者"昨天的代码是怎么写的"，直接让AI比对Git记录即可。老师傅向你解释几个有用的命令：
git log：查看提交历史，显示所有存档记录。如果你只想看最近 5 条，用git log -5。git diff：查看当前未提交的修改——也就是说，AI 改完代码但还没存档，你可以用这个命令检查它改了什么。git diff HEAD~1：对比上一个版本，看看最近一次提交改了什么。git show <commit-id>：查看某次具体提交的详细内容。
回滚
第二章提到 Git 是你的"后悔药"。下面展示三个场景：
场景一：改错了，还没提交
你发现 AI 刚改的代码一团糟，但它还没执行 git commit。最简单的方式：
git checkout -- <文件路径>：撤销某个文件的修改，恢复到上一次提交的状态。- 或者直接让 AI："撤销对 xxx 文件的所有修改"。
场景二：已经提交了，但想回到上一个版本
AI 刚提交完，你一跑项目发现崩了。你想回到上一个能跑的版本：
git reset --hard HEAD~1：回退到上一个提交，丢弃当前的所有修改。git reset --hard <commit-id>：回退到指定的某个版本。
场景三：已经推送到云端了
最麻烦的情况：错误的代码已经 git push 到远程仓库了。这时候 git reset 会失效，因为你的本地历史和云端对不上了。
老师傅教你一个更安全的命令：
git revert <commit-id>：创建一个新的提交，用来"撤销"指定提交的修改。这样历史记录是连续的，不会打断云端仓库。
你完全可以把这些操作交给 AI。比如直接说："回滚到上一个能跑的版本"或"撤销最近一次提交"，AI 会自动执行正确的命令。
分支
随着项目变大，你可能想尝试一个新功能，但又怕把现有代码搞坏。这时候就需要分支（Branch）。
老师傅用一个比喻解释分支：就像游戏的"存档槽"。主线叫 main 或 master，你可以开一个新分支比如 feature-login，在新功能上折腾。折腾坏了，切换回主线就行；折腾好了，把新分支合并到主线。
核心命令：
git branch <分支名>：创建新分支。git checkout <分支名>：切换到指定分支。现代写法是git switch <分支名>。git checkout -b <分支名>：创建并切换到新分支，一条龙搞定。git merge <分支名>：把指定分支合并到当前分支。
在协作场景中，分支很重要：每个人在自己的分支上开发，完成后再合并到主线，这样不会互相干扰。
Pull Request 代码审查
老师傅告诉你，在真正的团队协作中，直接把分支合并到主线是危险的做法。你可能不小心引入了 Bug，或者代码质量不够好，影响了整个项目的稳定性。
于是，Pull Request（简称 PR） 应运而生。PR 的字面意思是"拉取请求"，但更准确的理解是"合并请求"。当你在自己的分支上开发完功能后，不是直接合并，而是发起一个 PR，说："嘿，我开发了一个新功能，请你们检查一下代码，没问题再合并进去。"
这个流程的核心价值是代码审查（Code Review）：团队其他人查看你的代码，提出改进建议，发现潜在问题。研究显示，良好的Code Review能减少80%以上的错误。在AI编程时代，你可以在发起PR前让AI做Self-Review，检查逻辑错误、安全漏洞、性能问题、代码风格等，这样提交的PR质量更高。
PR还带来两个好处：自动化检查（平台自动运行测试，不通过就不允许合并）和讨论记录（在具体代码行下留言，所有讨论被记录下来）。
老师傅说，虽然对于小团队或者个人项目，PR可能显得有些繁琐。但当你开始与他人协作，尤其是参与开源项目时，PR是必不可少的工作流程。不过一开始不用太纠结分支策略，先把主线的自动提交养成习惯，等项目复杂度上来了再引入分支管理。
冲突解决
既然是协作，难免会遇到冲突的情况：当你和朋友同时修改了同一个文件的同一行代码，Git 无法判断该听谁的。
在 Vibecoding 时代，你不需要面对那些令人头大的 <<<<<<< HEAD 符号手足无措。 你只需要把包含冲突标记的文件内容直接发给 AI，对它说：
"解决这个 Git 冲突。保留我和远程最新的逻辑，如果逻辑冲突，请以我的为准（或以远程为准）。"
AI 会帮你完美合并代码，你只需要把修复后的代码复制回去，再次提交即可。
通过 Git，你和朋友可以同步代码了。但老师傅告诉你，除了代码，你们团队的许多"隐性知识"——命名约定、工作流程、调试技巧——也需要共享。这些还可以通过 Agent Skills 来编码成可复用的知识单元。把 Skills 提交到 Git，队友拉取代码后，他们的 AI 就自动学会了这些团队约定。有关 Skills 的开发与使用，我们会在后续内容中讲解。
Git 工作流最佳实践
日常开发三件套：
git add . # 暂存所有修改
git commit -m "描述" # 提交到本地
git push # 推送到远程提交信息规范（Conventional Commits）：
feat:新功能fix:修复 Bugdocs:文档更新style:代码格式refactor:重构test:测试chore:构建/工具
示例：
git commit -m "feat(auth): 添加用户登录功能"
git commit -m "fix(api): 修复登录接口超时问题"团队协作黄金法则
跨平台协作三原则：
配置 .gitignore：防止污染队友环境
- ❌ 绝不提交：
node_modules、.env、密钥文件 - ❌ 系统垃圾：
.DS_Store、Thumbs.db - ✅ 使用模板：github/gitignore
- ❌ 绝不提交：
统一换行符：避免假 diff
bash# Git 配置 git config --global core.autocrlf input # Mac/Linux git config --global core.autocrlf true # Windows统一路径分隔符：永远使用
/javascript// ✅ 正确 import { Button } from 'src/components/Button'; // ❌ 错误 import { Button } from 'src\\components\\Button';
Git 安全警告
⚠️ 绝对不能提交的内容：
- ❌ API 密钥、Token、证书
- ❌ 数据库密码、连接字符串
- ❌ 私钥（
.pem、.key、id_rsa） - ❌ 环境变量文件（
.env、.env.local） - ❌ 个人敏感信息
检查清单：
# 提交前检查
git diff --cached --name-only | grep -E '\.(env|pem|key)$'如果已提交？立即撤销：
# 从历史中彻底删除（危险操作）
git filter-branch --force --index-filter \
"git rm --cached --ignore-unmatch .env" \
--prune-empty --tag-name-filter cat -- --all
git push origin --force --all常见协作问题速查
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 推送失败 | 远程有新提交 | git pull --rebase |
| 拉取冲突 | 两人修改同一处 | 见"冲突解决"章节 |
| Windows 提交 CRLF | 未配置 autocrlf | git config core.autocrlf true |
| 文件找不到 | 大小写问题 | 统一使用小写命名 |
| node_modules 污染 | 未配置 .gitignore | 添加 node_modules/ |
冲突解决提示：
"把冲突内容发给 AI，说：解决这个 Git 冲突，
保留我和远程最新的逻辑，如果逻辑冲突，请以我的为准"小节导航
- 10.1 Git数据流向 (./01-Git数据流向.md) 🔴 - 理解 Git 的三区模型和数据流转
- 10.2 GitHub/Gitee仓库创建 (./02-GitHub-Gitee仓库创建.md) 🔴 - 从零开始创建和配置云端代码仓库
- 10.3 SSH详解 (./03-SSH详解.md) 🔴 - 理解 SSH 原理、配置和故障排查
- 10.4 跨平台协作问题 (./04-跨平台协作问题.md) 🔴 - 解决 Windows、Mac、Linux 之间的协作差异
- 10.5 Git常用命令 (./05-Git常用命令.md) 🔴 - 掌握日常开发中最常用的 Git 命令
- 10.6 回滚操作实战 (./06-回滚操作实战.md) 🔴 - 掌握各种回滚场景的解决方案
- 10.7 分支管理 (./07-分支管理.md) 🔴 - 理解分支模型和团队协作策略
- 10.8 冲突解决实战 (./08-冲突解决实战.md) 🔴 - 从容应对 Git 合并冲突
- 10.9 Pull Request工作流 (./09-Pull-Request工作流.md) 🔴 - 理解 PR 流程和代码审查
- 10.10 Skills团队知识共享 (./10-Skills团队知识共享.md) 🟡 - 使用 Skills 编码和共享团队规范
- 10.11 Agent Skills团队协作 (./11-Agent-Skills团队协作.md) 🟡 - 使用 Agent Skills 构建智能团队工作流