同步上游更新

从 upstream 远程把模板的新版本合并进你的项目,并用项目自带的检查验收。

你的项目是从模板仓库克隆出来的,而模板仓库会持续更新。更新的方式是从 upstream 远程合并。把你的改动放在留给你改的目录里,合并时的冲突就少。

准备工作

  • 干净的工作区:改动已提交或已暂存。
  • 对 GitHub 上模板仓库的只读权限。见获取 Kernlift。
  • 项目已推送到你自己的私有仓库,作为 origin。见代码仓库可以 fork 吗?
  • 目标版本的 CHANGELOG.md。破坏性变更标有 Breaking,并附带迁移说明。

把改动放在你的区域

区域路径
属于你的区域src/config/site.ts、src/components/marketing/example-landing.tsx、src/i18n/locales、public
模板骨架src/server、src/components/ui、scripts、drizzle/migrations、src/router.tsx、src/start.ts、src/server-entry.ts

骨架从不引用你的区域,唯一的例外是 src/config/site.ts。pnpm validate:template-boundary 检查这条规则。

合并一次更新

添加一次上游远程

git remote add upstream git@github.com:kernlift/kernlift.git
git fetch upstream

业务模板则换成该模板自己的仓库(kernlift/<template-key>)。

在分支上合并更新

git fetch upstream
git checkout -b upgrade/upstream-update main
git merge upstream/main

用合并,不要变基,这样不会改写你项目的提交历史。如果距离上次同步已经改动很多,用 git cherry-pick <commit> 只取需要的改动,不要一次全部合并。

解决冲突

  • 你的区域:保留你的,再看上游是否新增了你也需要的键。这种情况最常出现在字典文件中。
  • 骨架:取上游,再重新应用你的改动。如果同一文件反复出现这种情况,把改动移到骨架调用的模块里。
  • drizzle/migrations:不要修改已有迁移。原样取上游的迁移链,在其上加你自己的迁移。
  • package.json:两边的依赖都保留,然后 pnpm install。
  • 部署文件(deploy.config.json 以及 wrangler.jsonc、fly.toml、.railway/railway.ts 或 compose.yaml):保留你的。这些文件记录了你的平台和资源 id。如果上游改了你所用平台的文件,手动合入上游的改动,然后运行 pnpm cf-typegen。

验收更新

pnpm install
pnpm cf-typegen
pnpm db:migrate
pnpm typecheck
pnpm build
pnpm validate:all

推送到你的仓库

git checkout main
git merge upgrade/upstream-update
git push origin main

验证

  • 打开 /setup,确认没有必需项变成 未就绪。
  • pnpm validate:all 没有新增失败。对照你合并的上游提交上的 scripts/validate/known-failures.json。
  • 运行 git describe --tags $(git merge-base HEAD upstream/main) 查看当前所在版本。版本标签与变更日志条目一一对应。

常见问题

新的后台页面提示 "Permission denied"

这次更新新增了权限。按快速开始里同样的 SUPER_ADMIN_EMAIL 和 SUPER_ADMIN_PASSWORD 再运行一次 pnpm db:bootstrap-super-admin,让 Super Admin 角色获得这些权限。

合并后 pnpm db:migrate 失败

某个已有迁移被修改,或两条迁移链出现分叉。把上游的迁移文件原样恢复,在其上添加你的迁移,然后运行 pnpm validate:migrations。

同一个骨架文件每次合并都冲突

你把改动留在了上游也会修改的文件里。把改动移到你的区域,或移到骨架调用的插件里,下次合并就不会再碰到它。见插件。

git fetch upstream 提示 "Repository not found"

git 客户端使用的 GitHub 账号不是激活购买时填写的那个,或者邀请一直没有接受。到已购模板(/zh/app/licences)查看;见邀请过期了怎么办?

参考

下一步