GitHub:远程与协作
本合集目录
本章目录
单册说明:本文件是卷 3 的第 3 章,可独立阅读。前置:第 1 章(三区)、第 2 章(分支与合并)。本章把仓库从"你自己的硬盘"搬到远端,并第一次走完"开分支 → 推送 → 提 PR → 评审 → 合并"的完整流程。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 3 · 工程化与版本控制(第 3 / 7 章) |
| 前置章节 | 3.2 分支、合并与冲突 |
| 本章产出 | 一个远端仓库 · 一对 SSH 密钥 · 一份 .gitignore · 一次已合并的 PR · 一份密钥泄露处置流程 |
| 对应代码 | dudao/(新增 .gitignore,其余不动) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | git push 不用查资料;看到 ! [rejected] 知道先 pull 而不是 push -f |
3.3.1 一句话结论:远程是"另一份仓库 + 一个网页界面"
远端仓库不是云盘,也不是备份工具。它就是一个跑在别人服务器上的、裸的 .git 目录,外加一层网页界面让你看提交、看差异、提合并请求。你 push 上去的东西,和本地 .git/objects 里的东西是同一种对象。
真实失败场景:改完代码 git push,终端回你一句 Permission denied (publickey)。你以为是网络问题,换了 WiFi、重启了电脑、甚至重装了 Git——真正的原因是 SSH 密钥根本没配,或者配了但没加到账号里。这类错误信息很明确,只是没人教过你怎么读。
3.3.2 原理:三个名字别搞混
① origin、origin/main、main 是三个东西
| 名字 | 是什么 | 存在哪 | 谁能改 |
|---|---|---|---|
main |
你本地的分支 | 本地 ref 文件 | 你 |
origin |
远程仓库的别名,指向一个 URL | .git/config |
git remote 命令 |
origin/main |
远程跟踪分支:上次 fetch 时远端 main 的样子 |
本地 ref 文件 | 只有 fetch/pull/push 会更新它 |
关键点:origin/main 不是你连上远端实时看的结果,而是一张上次同步时的快照。所以完全可能出现"网页上明明有新提交,我本地 git log 看不到"——因为你还没 fetch。
本地 main ──push──▶ 远端 main
▲ │
└──── pull ─────────┘(= fetch 更新 origin/main,再 merge 进 main)
② SSH 还是 HTTPS
| 维度 | SSH | HTTPS |
|---|---|---|
| 地址样子 | [email protected]:you/dudao.git |
https://github.com/you/dudao.git |
| 认证方式 | 一对密钥,配一次长期有效 | 账号密码 / 个人访问令牌(token) |
| 首次配置 | 生成密钥 + 上传公钥 | 生成 token + 交给凭据管理器 |
| 网络限制 | 走 22 端口,部分公司/校园网封 22 | 走 443,几乎都能通 |
| 适合 | 自己的机器、长期开发 | 临时机器、22 端口被封、CI 环境 |
推荐 SSH,因为一次配好不再输入任何东西。如果 22 端口被封,SSH 也能改走 443(在 ~/.ssh/config 里给主机指定 Port 443 与 Hostname ssh.github.com),但那是应急手段,不是首选。
③ push / pull / fetch 的分工
| 命令 | 动远端 | 动本地分支 | 动工作区 | 一句话 |
|---|---|---|---|---|
git fetch |
否 | 只更新 origin/* |
否 | 只"看看远处有什么",最安全 |
git pull |
否 | 是(merge 或 rebase) | 是 | fetch + 合并进当前分支 |
git push |
是 | 更新 origin/* |
否 | 把本地提交送上去 |
新手最该养成的一个习惯:动手合并之前先 git fetch 看一眼。
git fetch
git log --oneline HEAD..origin/main
有输出,说明远端有你没有的提交;空输出,说明你在最新。这条命令比"先 pull 一下再说"安全得多,因为 pull 会直接改你的工作区。
④ PR 到底是什么
PR(Pull Request,合并请求)不是 Git 的功能,是托管平台加的一层工作流。它做三件事:
- 把一条分支的差异摆出来:
feature/tag-filter相对main改了哪些行,逐行显示。 - 提供一个讨论位置:可以针对某一行留言,而不是在聊天软件里说"你那个第 42 行"。
- 留下合并记录:谁提的、谁批的、什么时候合的、CI 过没过。
Code Review 的价值不在于抓错别字,而在于三件事:让第二个人理解这段代码为什么这么写;让"能不能上线"变成一个有人签字的决定;让知识不只存在一个人脑子里。哪怕只有你一个人开发,PR 也值得走——三天后的你就是那个需要评审的陌生人。
⑤ .gitignore 该写什么
规则只有一条:能由命令重新生成的东西,不进仓库;不能公开的东西,绝不进仓库。
# 依赖:由 package-lock.json 还原
node_modules/
# 构建产物:由 npm run build 生成
dist/
# 环境变量:含密钥与本机路径
.env
.env.local
.env.*.local
# 编辑器与系统
.vscode/
.DS_Store
Thumbs.db
# 日志与临时文件
*.log
npm-debug.log*
| 写法 | 含义 | 注意 |
|---|---|---|
dist/ |
忽略任意层级的 dist 目录 |
结尾斜杠表示只匹配目录 |
/dist |
只忽略仓库根下的 dist |
开头斜杠锚定根目录 |
*.log |
任意 .log 文件 |
不含目录本身 |
!important.log |
取消忽略 | 必须写在对应规则之后 |
已经跟踪的文件,加进 .gitignore 不会自动失效——Git 只对"未跟踪"的文件应用忽略规则。要让它失效:
git rm --cached .env
这一步只从索引里摘掉,磁盘上的文件还在。.env 必须配 .env.example:前者被忽略,后者提交,里面只有键名和假值,告诉后来的人需要配哪些变量。
⑥ 密钥泄露了怎么办
先记住一句:只要推送过,就当作已泄露。 改历史能让仓库里看不到,但抓取过的缓存、告警系统的记录、别人的本地克隆都还在。
| 阶段 | 处置 |
|---|---|
| 只在暂存区 | git restore --staged .env,然后加进 .gitignore |
| 已提交、未推送 | git rm --cached .env + git commit --amend --no-edit |
| 已推送 | ① 立刻到服务商后台吊销并重建密钥;② 用 git filter-repo 清历史;③ 强推并通知协作者重新克隆;④ 检查账单与访问日志 |
顺序不能反:先换密钥,再清历史。 反过来做,等于花两小时擦干净一个还在漏水的管子。git filter-repo 是独立工具,需要单独安装;旧文章里的 git filter-branch 已被官方标记为不推荐,不要再用。
⑦ 提交信息是给谁看的
PR 的标题和提交信息,第一读者不是别人,是半年后排查问题的你。一条能用的提交信息只有两部分:做了什么(动词开头)+ 为什么。行数控制在 50 字内,细节放正文。
| 写法 | 评价 |
|---|---|
改了一下 |
不可用。半年后无法判断影响范围 |
update app.js |
不可用。文件名不能说明意图 |
fix: 标签选中态比较顺序写反 |
可用。类型 + 现象 + 原因 |
feat: 列表空状态提示 |
可用。一眼知道 main 多了什么能力 |
前缀固定四个就够:feat(新功能)、fix(修缺陷)、chore(杂务:依赖、配置)、docs(文档)。这套约定不是强制标准,但它让 git log --oneline 变成一份能扫读的变更记录——发版前想知道"这次多了什么",扫一遍前缀就够了。
3.3.3 动手:从零推到远端,并开一次 PR
第 1 步:先在本地把"不该进仓库的"挡住
在 dudao/ 根目录新建 .gitignore,内容用上面那份。然后确认它生效:
git status -s
形如:
?? .gitignore
只有 .gitignore 是新的;如果 node_modules 已存在,它不会出现在列表里——说明规则生效了。
提交:
git add .gitignore
git commit -m "chore: 添加 .gitignore"
第 2 步:生成 SSH 密钥
先看有没有现成的:
ls ~/.ssh
有 id_ed25519 和 id_ed25519.pub 就跳过生成。没有则:
ssh-keygen -t ed25519 -C "[email protected]"
一路回车即可(密码短语可留空,本地机器图方便;共用电脑建议设)。形如:
Your identification has been saved in /c/Users/you/.ssh/id_ed25519
Your public key has been saved in /c/Users/you/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:9xQ... [email protected]
.pub 结尾的是公钥,可以随便给人;没有 .pub 的是私钥,绝不外传、绝不进仓库。
查看并复制公钥:
cat ~/.ssh/id_ed25519.pub
形如:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... [email protected]
把整行粘到托管平台的 SSH 设置页,标题随便写(建议写机器名,方便以后吊销)。
第 3 步:验证握手
ssh -T [email protected]
首次连接会问 Are you sure you want to continue connecting (yes/no)?,输入 yes。成功时形如:
Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.
看到这句就通了。 注意它开头是 Hi 你的用户名,说明平台认出了你;如果显示 Permission denied (publickey),见本章坑 3。
第 4 步:建远端仓库并关联
在网页上新建一个空仓库(不要勾选自动生成 README、.gitignore、License——勾了就会和本地历史无关,首次推送会被拒)。然后:
git remote add origin [email protected]:yourname/dudao.git
git remote -v
形如:
origin [email protected]:yourname/dudao.git (fetch)
origin [email protected]:yourname/dudao.git (push)
首次推送并建立跟踪关系:
git push -u origin main
形如:
Enumerating objects: 18, done.
Counting objects: 100% (18/18), done.
Writing objects: 100% (18/18), 4.21 KiB | 1.20 MiB/s, done.
To github.com:yourname/dudao.git
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
-u 只在这一步需要,它把本地 main 和 origin/main 绑定;以后直接 git push 即可。
第 5 步:开分支,改,推
git switch -c feature/empty-state
给列表加一个"还没有摘录"的空状态(app.js 里 renderList 开头判断 notes.length === 0 就渲染一行提示)。提交后推送:
git push -u origin feature/empty-state
形如:
remote:
remote: Create a pull request for 'feature/empty-state' on GitHub by visiting:
remote: https://github.com/yourname/dudao/pull/new/feature/empty-state
remote:
To github.com:yourname/dudao.git
* [new branch] feature/empty-state -> feature/empty-state
第 6 步:提 PR,看差异,合并
打开上面那个链接,或去仓库页面的 Pull requests → New pull request,base 选 main,compare 选 feature/empty-state。填写:
| 栏位 | 写什么 |
|---|---|
| 标题 | 一句话说清改了什么,如 feat: 列表空状态提示 |
| 描述 | 为什么改、怎么验证、有没有副作用 |
| Reviewer | 有协作者就指定;没有就自己过一遍 Files changed |
Files changed 页要自己先读一遍。 重点看三样:有没有误带的文件(.env、node_modules)、有没有调试用的 console.log、diff 里有没有你没想到的改动。这一步能拦掉大半"提交了不该提交的东西"。
合并方式选 Squash and merge(把这条分支的多次提交压成一条进 main)还是 Merge commit,取决于团队约定。单人项目用 squash,main 的历史更干净;需要保留每个中间步骤时用 merge。
合并后回到本地:
git switch main
git pull
git branch -d feature/empty-state
git pull 此时会做一次 fast-forward 或 merge,取决于平台用的是哪种合并方式。如果用 squash 合并,最后一条会失败:
error: The branch 'feature/empty-state' is not fully merged
因为 squash 生成的是一条新提交,原分支那两个提交并没有成为 main 的祖先,Git 认为删了会丢东西。确认内容确实已经在 main 里之后,用 git branch -D 强制删除。这不是报错,是 Git 在替你确认。
3.3.4 三个坑
坑 1:! [rejected] main -> main (fetch first)
症状:
! [rejected] main -> main (fetch first)
error: failed to push some refs to 'github.com:you/dudao.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref.
成因:远端有你本地没有的提交。最常见的是建仓库时勾了"添加 README",平台替你生成了一条提交;也可能是你在另一台机器上推过。
修法:先拉再推,不要 push -f。
git pull --rebase origin main
git push
--rebase 把你的本地提交接到远端提交之后,历史是一条直线,不会多出一个无意义的合并提交。如果两边改了同一处,会走上一章的冲突流程。
坑 2:把 .env 提交上去了
症状:仓库里能看到 .env,或者平台的密钥扫描直接给你发告警邮件。有时更隐蔽——文件被删了,但历史里还在,git log --all -- .env 依然能看到内容。
成因:.gitignore 写晚了,或者用了 git add -f 强行加入。
修法:按"阶段"处置(见 3.3.2 的表)。已经推送的情况,完整流程是:
# 1. 先去平台后台吊销旧密钥,生成新的,写进本地 .env
# 2. 从当前版本移除
git rm --cached .env
git commit -m "chore: 移除误提交的环境变量文件"
# 3. 清历史(需先安装 git-filter-repo)
git filter-repo --path .env --invert-paths
# 4. 强推所有分支与标签(这一步会改写远端历史,务必先通知协作者)
git push --force --all
git push --force --tags
第 4 步是破坏性的:所有协作者必须重新克隆,否则他们的历史和远端对不上。另外,git filter-repo 出于安全考虑会自动移除 origin 远端,重写后要重新执行 git remote add origin [email protected]:yourname/dudao.git 再推。所以真正省事的做法永远是第 1 步之前就写好 .gitignore。
坑 3:Permission denied (publickey)
症状:
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
成因:四种,按概率排——① 公钥没加到账号;② 私钥权限太松,SSH 拒绝使用;③ ssh-agent 没加载密钥(多密钥场景);④ 网络封了 22 端口。
修法:逐条排查。
ssh -vT [email protected]
-v 会打出握手细节,看它有没有尝试你预期的那把钥匙。私钥权限问题会明确报警:
WARNING: UNPROTECTED PRIVATE KEY FILE!
Permissions 0644 for '/home/you/.ssh/id_ed25519' are too open.
Linux/macOS 上改成 chmod 600 ~/.ssh/id_ed25519。Windows 上如果 Git Bash 报同样的错,通常是文件继承了过于宽松的 ACL,可以在"属性 → 安全 → 高级"里关闭继承,只保留当前用户。
多密钥时在 ~/.ssh/config 里显式指定:
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
如果确认是 22 端口被封(ssh -vT 卡在 Connecting to github.com port 22 后超时),改用 HTTPS,或按平台文档把 SSH 切到 443。
本章验收
- 能画出
main、origin/main、origin三者的关系,并说出谁在什么时候更新 -
ssh -T [email protected]返回Hi 用户名!的成功提示 - 远端仓库有一次自己推上去的提交,
git remote -v显示 origin 的 fetch 与 push 两行 -
.gitignore已提交,git check-ignore -v node_modules能指出规则位置 - 完整走过一次 PR:开分支 → 推送 → 提 PR → 自己看 Files changed → 合并 → 本地
pull - 能说出密钥泄露后的正确顺序:先吊销重建,再清历史,最后通知
自测
Q1:网页上明明有一条新提交,你本地 git log 看不到,origin/main 也看不到。为什么?
看答案
因为 `origin/main` 只是上次同步时的快照,不会自动更新。你需要 `git fetch` 才会把远端的新提交取下来并移动 `origin/main`。`git log` 默认只看当前分支,所以即便 fetch 过,也要用 `git log origin/main` 或先合并才能看到。Q2:git pull 和 git fetch 最本质的区别是什么?什么场景必须用 fetch?
看答案
`fetch` 只更新远程跟踪分支,不动你的分支和工作区;`pull` 等于 fetch 之后再 merge(或 rebase),会直接改你的工作区。想先看看远端改了什么、再决定要不要合的时候必须用 fetch,比如上线前确认别人有没有推新代码,或者本地有未提交改动不想被打断。Q3:为什么"删掉仓库里的 .env 再提交一次"不算修好泄露?
看答案
因为 Git 的历史是不可变的,删除只是新增一条提交,旧提交里的文件内容仍然可以通过 `git log`、`git show` 或克隆完整历史取到。只要推送过,就必须把密钥当作已泄露:先吊销重建,再用工具重写历史并强推,最后通知所有克隆过的人。密钥的价值在于"能不能用",换掉才是真正止血。下一步
版本管理这一层齐了:本地有历史,远端有备份,协作有 PR。但 app.js 还是一个大文件——下一章把它拆成四个模块,并解释为什么拆完之后双击 index.html 就打不开了。