用 Git 维护个人网站

这套流程适合一个常见的个人网站场景。代码平时在开发分支上修改，确认无误以后再进入 main。Cloudflare Pages 监听仓库里的分支，为开发分支生成预览，为 main 部署正式网站。

同步 main
   ↓
本地修改 → 自动检查 → 提交开发分支 → Preview 验收
                                      ↓
                                  合并 main
                                      ↓
                                  正式部署

每个箭头都对应一次可以验证的状态变化。Git 状态确认分支是否放对，自动检查确认网站能否交付，Preview 负责检查真实部署，main 只负责发布。

本文使用这个网站当前的分支安排。

main                  生产分支，对应正式网站
v3                    当前开发分支
feat/*                新功能分支
fix/*                 修复分支

如果你正在使用 feat/* 或 fix/*，把后文命令里的 v3 换成实际分支名即可。

开始修改前先把分支放对

进入项目，切换到开发分支，再看一眼工作区状态。

cd ~/Projects/knowledge-site
git switch v3
git status --short --branch
git fetch origin

git status --short --branch 会显示当前分支，也会列出尚未提交的文件。这里值得停几秒， 确认自己没有带着上一次留下的修改开始新工作。

git fetch origin 只更新远程分支信息，不会改动当前文件。远程 main 如果已有新提交， 可以把最新的生产版本接到开发分支上。

git rebase origin/main

rebase 没有冲突时会直接结束。出现冲突后，打开 Git 标出的文件，处理冲突内容，再继续。

git add 冲突文件
git rebase --continue

如果发现这次 rebase 不该继续，可以回到开始前的状态。

git rebase --abort

在本地运行网站

本地需要 Node.js 22 或更高版本。完整检查还会用到 Deno 2。第一次拉取项目时，先按 锁文件安装依赖。

npm ci

平时启动开发服务器只需要运行下面的命令。

npm run dev

浏览器访问 http://localhost:4321/。改了布局或交互以后，桌面和移动端都要看一遍。 开发页面能打开，只能说明本地服务器正常运行。类型、构建和站内链接还要交给提交前检查。

需要查看生产构建的结果时，先构建，再启动本地预览。

npm run build
npm run preview

提交前检查网站

这个项目把常用检查收进了一个命令。

npm run verify

它会检查格式、脚本语法、Astro 类型和生产构建，还会核对站内链接、搜索索引、草稿排除、 文章元数据、RSS、sitemap、robots、CSS 资源引用、标签 slug 冲突和 Git 空白字符。 看到命令成功结束，才能确认这次修改通过了项目现有的自动检查。

需要单独定位问题时，可以拆开运行。

npm run format:check
npm run check:scripts
npm run build
npm run validate:site
git diff --check

测试通过以后，再检查自己准备提交的内容。

git status --short
git diff

暂存文件以后，还可以查看最终将进入提交的差异。

git diff --staged

命令	要确认的事情
git status --short	哪些文件被修改、删除或新增
git diff	尚未暂存的内容改了什么
git diff --staged	下一次提交会包含什么

这一步主要防止误加 dist/、.env、私人日记、公司资料和临时文件。自动检查关心网站能否 正常构建，提交者仍要判断每个文件是否应该公开。

提交并推送开发分支

确认差异以后，把修改提交到 v3。

git add .
git status --short
git commit -m "Update website content"
git push origin v3

git add . 会暂存当前目录下的全部改动，所以紧接着再看一次状态很有必要。提交说明应当写清 这次做了什么，例如 Update Git operations guide，以后查历史会省事很多。

这个项目的本地 v3 以上游 origin/main 为比较基准。推送时显式写出 origin v3， 可以保留这项设置。功能分支也应当写出实际分支名。

git push origin feat/分支名

推送以后，仓库里的 GitHub Actions 会安装依赖并重新运行 npm run verify。这项检查会 在 Pull Request 和非 main 分支的推送上触发。本地通过以后，仍要确认远程检查成功。

在 Preview 中检查真实页面

推送 v3、feat/* 或 fix/* 后，Cloudflare Pages 会生成 Preview Deployment。它比本地 开发服务器更接近实际部署环境，也适合在发布前分享给别人检查。

至少打开这些页面。

/
/learn/
/blog/
/notes/
/chatter/
/about/
/search/
/tags/
/timeline/
/404.html

再打开一篇文章，检查正文、标签链接、搜索、主题切换和移动端导航。页面或路由有改动时， 还要确认构建输出、搜索索引、sitemap 和 robots 是否符合预期。

首页
 ├─ 导航与最近更新
 ├─ 栏目页
 │   ├─ 文章列表
 │   └─ 筛选与空状态
 ├─ 文章页
 │   ├─ 正文与目录
 │   └─ 标签与返回按钮
 └─ 辅助入口
     ├─ 搜索与标签
     ├─ 时间线
     └─ 404

把确认过的版本发布到 main

推荐在 GitHub 创建一个从 v3 到 main 的 Pull Request。自动检查通过，Preview 也确认 无误以后，再合并 Pull Request。main 收到新提交后，Cloudflare Pages 会自动部署正式网站。

确定需要从本地直接发布时，可以运行。

git fetch origin main
git push origin v3:main

直接推送少了 Pull Request 提供的检查记录和合并确认，更适合你已经明确核对过分支差异的 情况。GitHub Actions 的 push 检查排除了 main，所以直接发布前要确认本地 npm run verify 和开发分支最近一次远程检查都已通过。

线上出错时怎样回滚

优先使用 git revert。它会创建一个抵消旧改动的新提交，原来的提交记录仍然保留，出了 问题也容易继续追查。

git switch main
git pull --ff-only origin main
git log --oneline --decorate -20
git revert 提交号
npm run verify
git push origin main

Cloudflare Pages 收到这个新提交后会重新部署。你也可以在 Cloudflare Pages 的 Deployments 页面选择以前成功的生产部署并执行 Rollback。页面回滚能较快恢复网站，之后 仍建议在 Git 里补上对应的修复提交，让仓库记录与线上状态重新一致。

线上恢复以后，把 main 的新提交接回开发分支。

git switch v3
git rebase origin/main

当前情况	合适的动作	结果
文件尚未暂存	git restore 文件路径	丢弃该文件的本地修改
文件误入暂存区	git restore --staged 文件路径	保留修改，只取消暂存
错误已经进入 main	git revert 提交号	增加一条回滚提交
线上需要先恢复	Pages Rollback	后续仍需补 Git 修复

改错文件时怎样恢复

恢复以前先看这个文件改了什么。

git diff -- 文件路径

丢弃尚未提交的修改，可以运行。

git restore 文件路径

文件已经暂存，但你想保留本地修改，只把它移出暂存区，可以运行。

git restore --staged 文件路径

需要取回旧提交里的单个文件，可以指定提交号。

git restore --source 提交号 -- 文件路径

这些命令处理的对象不同。执行前确认文件路径和当前差异，尤其要留意 git restore 文件路径 会丢弃该文件尚未提交的修改。

覆盖远程 main 前再确认一次

只有确认远程 main 上独有的提交可以舍弃时，才考虑改写它的历史。先比较开发分支与远程 生产分支。

git fetch origin main
git log --oneline --left-right v3...origin/main

确认差异以后，使用带租约检查的强制推送。

git push --force-with-lease origin v3:main

不要把它换成普通的 --force。--force-with-lease 会在远程分支已经被别人更新时拒绝 覆盖，能挡住一部分误操作。它仍然会改写历史，不能代替发布前的人工确认。

一次完整的日常操作

熟悉各步骤以后，日常流程可以收拢成下面这组命令。

cd ~/Projects/knowledge-site
git switch v3
git status --short --branch
git fetch origin
npm ci
npm run verify
git add .
git status --short
git commit -m "Update website"
git push origin v3

推送完成后查看 Cloudflare Preview。确认页面无误，再通过 Pull Request 合并到 main。 本地检查、远程预览和正式发布各解决一类问题，把这三处都走完，一次网站更新才算结束。

开始工作      switch → status → fetch → rebase
本地检查      dev → verify → diff
提交预览      add → diff --staged → commit → push
正式发布      Actions → Preview → Pull Request → main
故障恢复      定位提交 → revert → verify → push