評估與合併範本更新

明確訂出更新目標，透過舊範本、新範本和業務專案的差異，保留自訂內容並引入需要的修改。

發布於 2026年9月20日

本篇供日後有明確更新需求時參考。目前範本沒有為自訂專案自動合併原始碼的工具，也不需要為了閱讀本文而立即更新既有專案。

一、先說明為什麼需要這次更新

開始前，先寫清楚三件事：希望解決什麼、準備採用哪個版本或提交，以及哪些業務必須維持原有行為。

例如，「引入某次郵件寄送修正，保留既有註冊規則和郵件文案」，比「同步最新範本」更容易評估和驗證。目標明確，才能判斷哪些變更是必要的，哪些可以留待日後處理。

範本版本與應用程式版本應分別記錄。修改應用程式的 package.json.version 不會執行原始碼或資料庫升級，升級 CLI 也不會修改已產生的應用程式。

有具體升級計畫時，再準備獨立分支或副本。先檢查既有工作，不要將自己尚未完成的修改與範本更新，混在一次大型變更中。

git status --short
git log -5 --oneline
git diff --stat

這些指令只讀取狀態。確認既有變更已妥善儲存後，再建立專門用於評估和合併的分支。Git 分支只能保留已提交的程式碼，不會備份 D1、上傳檔案、Secret 或第三方平台設定。

請保留原專案目錄，不要直接將新版 ZIP 解壓縮並覆蓋原目錄，也不要將重新執行 saavo create 當作就地升級。

理想情況下，應同時保留：

先比較「舊範本到新範本」，看清楚上游變更，再比較「舊範本到業務專案」，看清楚自己的修改。最後決定如何將上游變更套用至目前業務。

如果自己的儲存庫與範本沒有共同的 Git 歷史，應使用目錄比較或修補檔逐項處理，不要為了讓合併指令執行，就強行拼接無關歷史。只有確認存在可用的共同歷史和可靠遠端來源時，Git 合併才有明確基礎。

舊範本來源不明時，可以搭配專案初始提交、下載紀錄和檔案內容縮小範圍。無法確認的部分應記錄為不確定，不能將任意一個較舊版本當作實際起點。

CLI 會修改專案名稱、應用程式版本，以及 Worker、D1、R2、Queue 的資源名稱。正式部署後，也會寫入帳戶、資源 ID 和正式環境網址。發布的原始碼套件還會移除 package-lock.json 和維護者專用的 commit script。

這些差異不一定是遺漏或錯誤。比較時，請保留自己的專案身分和遠端繫結，不要使用新範本的預留設定，替換已投入使用的資源。

發生衝突時，先理解兩邊的業務意圖，再進行合併。例如，上游新增一種電子郵件驗證，不代表應直接覆寫專案既有的註冊原則，也不能因為保留舊程式碼，就遺漏該驗證依賴的安全性修正。

涉及資料庫存取時，請維持 schema → core/db → core/repositories → service → API → UI 的職責邊界。不要為了盡快消除衝突，讓頁面直接讀取資料庫型別，或讓 API 暫時組合 SQL。

選擇性合併時，請追蹤所需的關聯變更。一項修正可能同時新增欄位、遷移、設定項目和測試，只複製 Handler 容易留下執行時的缺漏。

先合併需要的相依套件宣告，再透過專案使用的套件管理器，產生一致的鎖定檔。不要手動拼接鎖定檔，也不要順便將相依套件升級擴大為所有套件的最新版更新。

當 package.json 有經過評估的相依套件變更時，可執行：

npm install

檢查產生的鎖定檔差異，確認沒有與本次目標無關的大量升級。後續在乾淨環境中，依已提交的鎖定檔安裝時，可以使用 npm ci。

若上游提高 Node.js 要求，也需要同步更新開發環境、建置環境和持續整合設定。請檢查專案的 engines、指令碼與相依套件要求，而非只看範本中的某份舊說明。

完成必要合併後，依本次修改執行檢查。設定可以先透過 npm run doctor 查看，Binding 有變更時，請重新產生型別。只有確實準備了資料庫變更，才執行對應的遷移驗證。

程式碼合併完成後，執行：

npm run verify

這會執行程式碼規範檢查、型別檢查、測試和建置。檢查通過後，也要重現本次要解決的問題，並驗證相鄰流程。例如，修正付款回呼後，應檢查重複投遞和權益授予，而不只是開啟首頁。

若出現與本次合併無關的既有失敗，應記錄並區分來源，不要悄悄放寬測試或刪除驗證，只為了讓指令通過。

發布前，應能清楚回答：引入了哪些上游變更、保留了哪些業務差異、是否需要資料或設定遷移、測試了什麼，以及失敗後如何恢復。

沒有資料變更時，可以進入驗證與發布。若涉及資料表結構、設定、資源或已儲存的 Key，請先閱讀資料與設定遷移。