全部文章

SaaScaffold 的更新如何合入你的站点

几乎每个模板都承诺终身更新。问题出在你改过代码之后:新版本改的正是你改过的文件,合并一次就是一下午的冲突,没过多久站点就再也不更新了。SaaScaffold 的结构让你定制之后更新仍能顺利合并,而且可以交给编码 Agent 来合并。

SaaScaffold 站点不是一个只能自己维护的分叉。它从一个底座版本开始,之后持续接收新版本,每个版本都是名为 base-v<版本号> 的 git 标签。升级就是把这个标签合并进你的站点。

每个路径都有归属

base-ownership.json 把每个路径分进三类之一:

  • 站点:你的配置、文案、样式、站点记录,以及你自己的表和迁移。底座只提供一次初始副本,之后不再修改。
  • 生成:由命令重建的文件,例如 pnpm-lock.yaml。保留你的副本,合并后重新生成。
  • 底座:其余所有文件,正常合并。

站点文件在 .gitattributes 中标记为 merge=ours,两边都改过时,git 直接保留你的版本,不产生冲突。每个新克隆运行一次 pnpm base:setup 来启用它。

你的代码放在哪里

你的代码放在 apps/web/src/site/:配置、文案、样式、首页、商品、支付渠道、AI 模型与价格、登录对话框和后台步骤。Worker 名称与 ID 写在 site/wrangler.jsonc,你的表放在站点迁移通道。新增的路由文件不会冲突。

如果必须修改底座文件,改动尽量小,并在 site/agents/ 里写明原因,让下一次升级的人知道要重新应用什么。

一次完整的升级

创建站点时做一次:让 git 分别指向底座和你自己的仓库。

git remote rename origin upstream          # 底座版本
git remote add origin <你的站点仓库>        # 你自己的仓库
pnpm base:setup

之后每次升级:

git fetch upstream --tags
pnpm base:doctor --target base-v1.3.0
git switch -c upgrade-base-v1.3.0
git merge base-v1.3.0

base:doctor 在合并前列出两边都改过的底座文件,让你提前知道冲突在哪里。合并后依次运行 pnpm install、pnpm wrangler:sync、pnpm db:migrate 和 pnpm test,然后照常部署。

用合并提交把升级分支并入 main,不要压缩或变基:下一次升级要靠这次合并找出变化。

合并会挡掉什么

merge=ours 保留你的副本,同时丢弃底座对该文件的改动。所以要读完当前版本到目标版本之间的每一节更新日志:其中列出新迁移、新配置项,以及需要你手动搬过来的站点文件改动。

也可以交给 Agent

上面的每一步也写成了给编码 Agent 的手册,随代码一起放在仓库里。AGENTS.md 把 Claude Code 或 Codex 引到 agents/README.md,后者把“合并新的底座版本”这类请求对应到 git 与升级手册。Agent 会运行 base:doctor,在单独的分支上合并标签,运行合并后的命令和测试,再用合并提交把分支并入。

手册还按文件类别告诉它如何处理每种冲突:

  • 站点文件冲突:说明这个克隆没有运行 base:setup。Agent 会中止合并、运行它,再重新合并。
  • 你改过的底座文件:从底座新版本出发,重新应用你的改动,最好挪进 apps/web/src/site/ 以免再次冲突,并更新 site/agents/ 里的说明。
  • 底座的表或迁移:停下来问你,因为正确的做法取决于生产环境已经运行过哪些迁移。它绝不会为了让合并通过而修改、重新编号或删除迁移。

遇到看不懂的冲突,它会把两边的内容拿给你看,而不是猜。它从不推送到底座仓库,推送到你的仓库或部署都要等你同意。

了解更多:扩展 SaaScaffold。