版本升级

已有自定义代码或数据，想同步更新模板时阅读这篇。全新安装直接走 快速开始，不需要先做升级。

将产品保存在自己的仓库

为产品创建私有仓库。直接克隆模板且 origin 仍指向模板时，可以将它改名为 upstream，再添加自己的仓库：

git remote -v
git remote rename origin upstream
git remote add origin YOUR_PRIVATE_REPOSITORY_URL
git push -u origin HEAD

如果 origin 已指向产品仓库，或已存在 upstream，不要直接执行改名。先检查 git remote -v 再调整，按许可要求保持仓库私有。

在独立分支引入更新

先提交现有产品改动并完成备份，在干净工作区执行：

git switch -c upgrade/template-update
git fetch upstream
git merge upstream/main
pnpm install

解决冲突时保留你的业务行为，不将未经审查的数据库变更直接合入生产。下方对照说明旧单应用/Hyperdrive 项目需要适配的变化，不是自动生产迁移脚本。

目录变化

• Node 应用：apps/web，给 Vercel/Docker，Postgres 连接池和 S3 兼容存储。
• Workers 应用：apps/web-cloudflare，D1 DB、原生 R2 R2_BUCKET、Cloudflare Email Sending。旧 Hyperdrive 架构不再是当前模板路径。
• 共享工厂与纯逻辑：packages/*。两应用保留完整页面副本，不抽共享 page 包。
• MDX 归每个应用的 content/；不是根目录共享内容文件夹。
• 消息归 packages/i18n/src/translations/{en,zh}/，加载 default.json 后深合并 mvp.json。衍生文案只改 mvp.json。
• 产品开关在 packages/config/src/index.ts；价格展示/可购买项仍在应用 src/config/saas/。

删除的能力与新配置

/app/admin/settings、设置 API、加密设置存储、MUSE_SETTINGS_SECRET 与数据库连接策略开关不属于当前版本。支付、Turnstile、邮件和 Node S3 凭据从服务端环境变量读取。不要保留指向旧后台设置页的入口。

旧邮件变量对应新 MAIL_FROM、MAIL_FROM_NEWSLETTER、CONTACT_FORM_TO，没有兼容回退。最新版本不提供旧的设置导出 CLI。升级前在旧版本上安全导出/记录自己的凭据，并在新宿主注入；切勿把密钥提交到代码或日志。

安全升级顺序

1. 备份已有代码、数据库、存储与凭据；在独立分支/环境演练。
2. 按真实产品改动迁移 routes、modules、包装层与包逻辑；不要整目录覆盖。
3. 将衍生消息迁到两语言的 mvp.json，保留上游 default.json。
4. 创建所选应用的 .env.local；Workers 同时维护 .dev.vars 和资源绑定。
5. 对照新旧 schema/迁移历史，为已有库设计增量迁移。新基线只用于新库。
6. 若从 Postgres 切到 D1，需单独迁移用户/业务数据，处理 SQLite 类型、约束和事务差异；配置绑定不会自动迁数据。
7. 运行下列检查，并在真实应用验证认证、权限、计费、上传和跨路由导航。

pnpm type-check
pnpm check:error
pnpm test:unit
pnpm apps:parity
pnpm build

对已配置应用运行 pnpm test:api 与 pnpm test:e2e。参见 测试 与 发布检查清单。

命令对照

裁剪应用还需同步 workspace、根脚本与测试配置，不要只删除目录。