跳到正文
零到全栈 · 卷 3 · 工程化与版本控制

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 的功能,是托管平台加的一层工作流。它做三件事:

  1. 把一条分支的差异摆出来:feature/tag-filter 相对 main 改了哪些行,逐行显示。
  2. 提供一个讨论位置:可以针对某一行留言,而不是在聊天软件里说"你那个第 42 行"。
  3. 留下合并记录:谁提的、谁批的、什么时候合的、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 就打不开了。

→ 卷3-04-从脚本到模块.md