同步上游更新
从 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)查看;见邀请过期了怎么办?