套件改进时更新你的副本

1. 记下你的起点

把更新当作一个小项目而不是一次粘贴：把你手上的套件版本与更新的版本对比，把变更带过来，在分支上测试后再部署。无论你的项目是套件存储库的 fork——GitHub 保持与源连接的副本——还是复制进你自己应用的代码，这套流程都适用。

在做任何事之前，先在项目中写一条笔记，记三件事：你开始的套件提交——SHA，Git 用来精确定位一个版本的短代码——你收到的存储库（supastack-web、supastack-mobile、supastack-desktop 或 All Platforms monorepo），以及你自己已经做过的改动。

各套件存储库与 monorepo 的历史不同，因此绝不要把一个仓库的分支合并进另一个仓库的 fork。如果你从没记过起始 SHA，在 fork 中用 git merge-base 找最接近的共同版本；选择性采用的话则找出你最后复制的文件和测试——当确切基线不确定时，审查范围更大的 diff。

2. 拉取并合并新版本

在项目文件夹内的终端中运行下面的命令，先保存并提交你的工作——保持工作区干净，避免半成品混进合并。尖括号里的词是待替换模板：用你自己的值替换整个 <thing>。示例中的 GitHub 地址是占位符；请使用你 fork 的存储库地址。

各行的作用：git remote add 给你的副本添加一个名为 kit-upstream 的第二个地址——套件存储库；git fetch 下载它的最新状态而不碰你的文件。git switch -c 创建独立的升级分支，审查期间你的主分支保持原样。git log 列出你即将接收的提交，git diff --stat 汇总哪些文件变了；对你用到的模块要读完整 diff，而不只是提交标题。git merge 把新代码带进升级分支。

如果 Git 报告 kit-upstream 远程已存在，跳过 remote add 那一行，直接继续 git fetch。<previous-kit-sha> 是第 1 步记下的起始 SHA。

# Upstream is the platform repository you forked — substitute its real URL
# (supastack-web shown; use supastack-mobile or supastack-desktop as fits).
git remote add kit-upstream https://github.com/<org>/supastack-web.git
git fetch kit-upstream
git switch -c upgrade/kit-update
git log --oneline <previous-kit-sha>..kit-upstream/main
git diff --stat <previous-kit-sha>..kit-upstream/main
git merge kit-upstream/main

3. 解决冲突而不丢失你的成果

冲突意味着两边改了同一批行：套件向前走了，而你自定义了相同的位置。Git 暂停合并并标记文件——它在请你做选择，而不是报告损坏。

在编辑器中逐个打开被标记的文件，逐行决定：保留你产品自己的文案、名字和设置，采纳套件的修复与结构性变更。绝不要用套件的新版本整体替换你自定义过的文件来解决冲突——那会抹掉你的工作。在升级分支内解决，并在继续之前为每块已解决的区域跑测试。

如果合并出了问题，git merge --abort 会把分支恢复到合并前的状态。在你自己合并升级分支之前，这个流程不会改动你的主分支或部署。

4. 按正确顺序更新数据并部署

新的套件版本可能改动数据库。先读 packages/db/drizzle/——迁移文件夹——里的新文件，并在应用迁移前备份生产数据；先拿一次性副本测试。先部署兼容的 schema 变更，再部署依赖它们的代码：如果迁移删除或重塑了数据，只回滚应用代码无法恢复旧 schema。

把新的 .env.example 与你自己的设置对比，在托管控制台补上新增的必填值。.env 文件装着机密，绝不提交到 Git——你要在每台机器、每个部署上手工重建它们，且机密永远不放进 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值。

部署前跑一遍套件自带的验证关卡。在 All Platforms monorepo 中，corepack pnpm check:local 运行 lint、类型检查、单元测试和格式检查，无需付费凭据；corepack pnpm verify:local 再额外加上生产构建和浏览器测试套件。单界面 fork 则运行该存储库自己的测试与构建命令。然后做一次预发冒烟：登录、试试第二个工作区、跑一遍产品的主流程。

全部通过后，记下接受的目标 SHA 和你解决过的冲突——这条笔记就是下次更新的起始基线。

corepack pnpm check:local
# fuller gate: adds the production build and browser suites
corepack pnpm verify:local

5. 如果你是复制片段而不是 fork

选择性采用——把套件模块复制进已有应用——与套件没有共享 Git 历史，因此 git merge 帮不上忙。改为对比旧的源 SHA 与目标源 SHA，只移植触及你所采用部分的变更。

把模块的公共类型、持久化 schema 与迁移、服务端调用方、配置、测试和文档当作一个整体审查——包内的一处变更可能需要别处配套的路由或环境变更，只复制一个 helper 会让其余部分停留在旧契约上。记一条简短的适配笔记——拿了套件哪些文件、跳过哪些、改了什么——下次更新就能按它重放你的选择。

如果更新弄坏了你运行中副本的某些功能，先按故障排查指南走一遍，再撤销自己的改动。

• 修复更新后的问题