评估与合并模板更新

明确更新目标，通过旧模板、新模板和业务项目的差异保留定制并引入需要的修改。

发布于 2026年8月22日更新于 2026年9月20日

本篇用于以后出现明确更新需求时参考。当前模板没有为定制项目自动合并源码的工具，也不需要为了阅读本文而立即更新现有项目。

一、先说明为什么需要这次更新

开始前写清楚三个问题：希望解决什么、准备采用哪个版本或提交、哪些业务必须保持原来的行为。

例如“引入某次邮件发送修复，保持现有注册规则和邮件文案”，比“同步最新模板”更容易评估和验证。只有目标明确，才能判断哪些变化必要，哪些变化可以留在以后处理。

模板版本与应用版本分别记录。修改应用的 package.json.version 不会执行源码或数据库升级，升级 CLI 也不会修改已经生成的应用。

有具体升级计划时，再为它准备独立分支或副本。先检查现有工作，不要把自己的未完成修改和模板更新混在一次大改动里。

git status --short
git log -5 --oneline
git diff --stat

这些命令只读取状态。确认已有修改已经妥善保存后，再创建专门用于评估和合并的分支。Git 分支只能保存已经提交的代码，不会备份 D1、上传文件、Secret 或第三方平台设置。

保留原项目目录，不要将新版 ZIP 直接解压覆盖进去，也不要把重新执行 saavo create 当作原地升级。

理想情况下同时保留：

先比较“旧模板到新模板”，看清上游变化，再比较“旧模板到业务项目”，看清自己的修改。最后决定如何把上游变化应用到当前业务。

如果自己的仓库与模板没有共同 Git 历史，应使用目录比较或补丁逐项处理，不要为了让合并命令运行而强行拼接无关历史。只有确认存在可用的共同历史和可靠远程来源时，Git 合并才有明确基础。

旧模板来源不明时，可以结合项目初始提交、下载记录和文件内容缩小范围。无法确认的部分应记录为不确定，不能把任意一个较旧版本当作真实起点。

CLI 会修改项目名、应用版本以及 Worker、D1、R2、Queue 的资源名称。正式部署后还会写入账户、资源 ID 和生产地址。发布源码包也会移除 package-lock.json 和维护者专用的 commit script。

这些差异不一定是遗漏或错误。比较时保留自己的项目身份和远程绑定，不要用新模板的占位配置替换已经投入使用的资源。

发生冲突时，理解两边的业务意图后再合并。比如上游增加一种邮箱校验，并不意味着应直接覆盖项目已有的注册策略，也不能因为保留旧代码就漏掉校验依赖的安全修复。

涉及数据库访问时，保持 schema → core/db → core/repositories → service → API → UI 的职责边界。不要为了尽快消除冲突，让页面直接读取数据库类型或让 API 临时拼 SQL。

选择性合并时，跟踪所需的关联变更。一个修复可能同时增加新字段、迁移、配置项和测试，只复制 Handler 容易留下运行时缺口。

先合并需要的依赖声明，再通过项目使用的包管理器生成一致的锁文件。不要手工拼接锁文件，也不要把依赖升级顺便扩大成所有包的最新版本更新。

当 package.json 有经过评估的依赖变化时，可运行：

npm install

检查生成的锁文件差异，确认没有与本次目标无关的大面积升级。后续在干净环境中按已提交锁文件安装，可以使用 npm ci。

若上游提高 Node.js 要求，还需要同步开发环境、构建环境和持续集成设置。检查项目 engines、脚本与依赖要求，而不是只看模板某一份旧说明。

完成必要合并后，根据本次修改执行检查。配置可以先用 npm run doctor 查看，Binding 有变化时重新生成类型。只有确实准备了数据库变更，才执行相应迁移验证。

代码合并完成后运行：

npm run verify

这会执行规范检查、类型检查、测试和构建。检查通过后还要复现本次要解决的问题，并验证相邻流程，例如修复支付回调后检查重复投递和权益发放，而不只是打开首页。

出现与本次合并无关的原有失败时，应记录并区分来源，不要悄悄放宽测试或删除校验让命令通过。

发布前应能清楚回答：引入了哪些上游变化、保留了哪些业务差异、是否需要数据或配置迁移、测试了什么、失败后如何恢复。

没有数据变化时可以进入验证与发布。涉及表结构、配置、资源或持久化 Key 时，先阅读数据与配置迁移。