專案指令
預設範本 package.json 中提供的開發、檢查、資料庫和部署指令。
本頁收錄 saavo-default-template/package.json 中的 npm scripts。除非另有說明，指令都應在初始化後的專案根目錄執行。原始碼套件會移除範本維護者使用的 commit 指令，因此不能將它視為新建專案的預設指令。
本頁依據範本原始碼版本 0.2.14 核對。執行 npm run 可查看自己專案實際支援的指令；舊範本可能存在差異。僅在 scripts 中新增指令名稱不會安裝對應實作，使用缺少的指令前應對照相應範本原始碼更新。
開發與預覽
| 指令 | 用途 |
|---|---|
npm run predev | 產生內容集合和搜尋索引；npm 會在 dev 前自動執行 |
npm run dev | 先產生搜尋索引，再啟動 Vite 開發伺服器 |
npm run build | 產生搜尋索引，以正式環境模式建置造訪統計指令碼和應用程式 |
npm run build:preview | 產生搜尋索引，以 local-preview 模式建置本機預覽版本 |
npm run preview | 執行 build:preview，然後在 127.0.0.1:4173 啟動 Vite Preview |
npm run build:analytics | 以開發模式單獨建置造訪統計指令碼 |
predev 是 npm run dev 的生命週期指令碼，npm 會自動執行，通常不需要手動執行。
程式碼檢查與測試
| 指令 | 用途 |
|---|---|
npm run lint | 產生內容集合並執行 ESLint |
npm run lint:fix | 產生內容集合並執行 ESLint 自動修正 |
npm run typecheck | 產生內容集合並執行 tsc --noEmit |
npm test | 依序執行應用程式、指令碼、OAuth 流量限制和 Durable Object 基礎元件測試 |
npm run test:app | 產生內容集合後執行應用程式測試 |
npm run test:scripts | 僅執行 scripts/ 對應的測試 |
npm run test:oauth-rate-limit | 僅執行 OAuth 流量限制測試 |
npm run test:primitives | 僅執行 Durable Object 基礎元件測試 |
npm run test:coverage | 產生內容集合後執行應用程式測試並產生涵蓋率報告 |
npm run verify | 依序執行 lint、typecheck、全部測試和正式環境建置 |
執行 npm run verify 可以完成全部本機檢查。建置成功不能取代型別檢查和測試。
內容與型別產生
| 指令 | 用途 |
|---|---|
npm run gen:collections | 根據內容目錄重新產生文件和部落格集合 |
npm run gen:search-index | 產生內容集合和站內搜尋索引 |
npm run cf-typegen | 根據 Wrangler 設定和環境變數重新產生 worker-configuration.d.ts |
npm run kv:sync:local | 產生內容集合，並將文件和部落格內容同步至本機 MAIN_KV |
npm run kv:sync:remote | 產生內容集合，並將文件和部落格內容同步至遠端 MAIN_KV |
src/libs/documentation/source/.content-collections/ 存放產生的集合、型別和快取，已由 Git 忽略，也不會包含在發布的原始碼套件中。saavo:init 會重新產生它；修改內容後，也可以執行 npm run gen:collections 重建。
本機初始化與檢查
| 指令 | 用途 |
|---|---|
npm run secret:generate | 輸出一個新的 256 位元標準 Base64 SAAS_SECRET，不會修改環境變數檔案 |
npm run saavo:init | 建立或保留 .env，補上缺少的 SAAS_SECRET，再依序執行 cf-typegen、gen:collections、db:migrate:local 和 doctor |
npm run doctor | 檢查本機環境變數、設定、Binding、資源名稱和資料庫目錄 |
npm run doctor:remote | 使用 .env.production 檢查正式環境設定、帳戶和資源 ID，不等於驗證全部遠端服務都可用 |
資料庫
| 指令 | 用途 |
|---|---|
npm run db:migrate:local | 初始化空白的本機 D1，並套用尚未執行的本機遷移 |
npm run db:migrate:remote | 初始化空白的遠端 D1，並套用尚未執行的遠端遷移 |
npm run db:reset:local | 刪除本機兩個 D1 中的資料表、檢視表和觸發程序，再執行初始化指令碼和資料庫遷移 |
npm run db:reset:remote | 完整輸入確認文字後，重設遠端兩個 D1，再執行初始化指令碼和資料庫遷移 |
重設指令會清空資料庫
db:reset:local 和 db:reset:remote 都會刪除既有資料。指令碼不提供復原操作，還原必須依靠事先準備並驗證過的備份或資料庫還原功能。不能使用重設指令更新正式環境的資料表結構。
修改資料庫結構時，應在 schema/migrations 中新增遷移檔案，再執行對應的 db:migrate 指令。請勿直接執行 schema/db-init.sql 或 schema/analytics-init.sql。
部署
| 指令 | 用途 |
|---|---|
npm run deploy:init | 首次部署：檢查本機專案，確認 Worker 和資源名稱，建立遠端資源，部署 Worker，初始化 D1，同步內容並執行健康狀態檢查 |
npm run deploy:update | 更新已初始化的專案：檢查遠端設定，執行完整驗證和資料庫遷移，部署 Worker，同步內容並執行健康狀態檢查 |
npm run domain:set -- https://app.example.com | 檢查正式環境設定，更新 wrangler.jsonc 和 .env.production 中的自訂網域設定，建置、部署並檢查首頁 |
deploy:init 僅用於第一次遠端部署。完成首次部署，且具備完整的遠端資源設定後，後續發布使用 deploy:update。僅寫入 account_id 不代表初始化已完成。若首次部署中途失敗，應先檢查已建立的資源和設定，再依部署教學處理，不能只根據某個欄位就切換指令。
deploy:update 要求 .env 和 .env.production 中的 SAAS_SECRET 存在且完全一致。遠端遷移會在部署新 Worker 之前執行，因此遷移必須與目前仍在線上執行的程式碼相容。
domain:set 僅修改 Worker 自訂網域和 VITE_SITE_URL。GitHub、Google、Stripe 等第三方平台的回呼網址，以及 Turnstile 和郵件寄送網域，仍需在各平台另外更新。
domain:set 不執行完整的 verify、資料庫遷移或 KV 同步。如果同時發布程式碼、資料結構或內容變更，應使用 deploy:update。
Stripe Webhook
| 指令 | 用途 |
|---|---|
npm run webhook:stripe:dev | 讀取 .env，使用測試模式金鑰建立 Webhook 目標，並寫回 STRIPE_WEBHOOK_SECRET |
npm run webhook:stripe:prod | 讀取 .env.production，使用正式環境模式金鑰建立 Webhook 目標，並寫回 STRIPE_WEBHOOK_SECRET |
這兩個指令會呼叫 Stripe 建立遠端 Webhook，不只是產生本機設定。指令碼會詢問接收網址、事件 API 版本和訂閱事件。開發環境應提供 Stripe 能夠存取的 HTTPS 網址，本機回送位址不能作為遠端傳送目標。正式環境設定寫回後，還需要重新部署。開發設定更新後，則需要重新啟動開發伺服器。
每次成功執行都會建立新的 Webhook 目標，不會更新既有目標。再次執行前應檢查既有目標，避免重複傳送事件。
版本與發布
| 指令 | 用途 |
|---|---|
npm run release:tag | 以互動方式選擇版本，為目前提交建立含說明的 v<version> 標籤，並僅將該標籤推送至 origin |
npm run release:archive -- <tree-ish> <output-path> | 將指定的 Git Tree 封裝為可重現的原始碼 ZIP |
release:tag 預設使用 package.json 中的版本號碼，不會修改檔案、建立提交或推送目前分支。輸入其他版本號碼時，指令碼會顯示警告，但仍允許繼續。
範本儲存庫的發布工作流程要求標籤與 package.json、package-lock.json 中的版本一致。請先提交所有待發布變更，再建立標籤；標籤推送成功不等於發布成功，還需檢查發布工作流程的結果。
release:archive 從 Git Tree 讀取檔案，不會將尚未提交的內容放入壓縮檔。壓縮檔會排除 package-lock.json，並從 package.json 中移除維護者使用的 commit 指令碼。
範本儲存庫維護指令
npm run commit -- "提交說明" 僅存在於範本原始碼儲存庫的 scripts 中，發布的原始碼套件會移除這項指令。它會暫存全部變更、準備下一個修補版本、建立提交，並直接推送目前分支。未傳入提交說明時，會以互動方式詢問。