套件改進時更新你的副本

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 會讓其餘部分停留在舊契約上。記一條簡短的適配筆記——拿了套件哪些檔案、跳過哪些、改了什麼——下次更新就能按它重放你的選擇。

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

• 修復更新後的問題