本機開發與建置

依相依套件、初始化、開發請求、內容產生和正式環境建置的順序，定位本機問題。

發布於 2026年9月20日

先區分問題發生在安裝相依套件、執行指令碼、啟動伺服器，還是開啟頁面之後。伺服器能監聽連接埠，不代表設定載入、資料庫存取和頁面呈現都已成功。

一、確認目錄與執行環境

所有指令都在 CLI 建立的應用程式專案根目錄執行，而非 saavo-cli 或文件網站儲存庫。不同儲存庫的 package.json 不同，不能直接套用它們的部署指令。

node --version
npm --version

目前範本的檢查要求 Node.js 至少為 22.13.0，檢查指令碼建議使用 Node.js 24。更換版本後，重新開啟終端機，確認實際使用的版本已切換。

如果看到 Missing script，先檢查目前目錄的 package.json。初始化用的原始碼套件不包含範本維護者的 commit script，應用程式也沒有預設的 deploy:prod script。完整清單請見專案指令。

初次使用發布的原始碼套件建立專案時，可能沒有 package-lock.json，請使用：

npm install

如果已有有效且與 package.json 一致的鎖定檔，希望依鎖定版本重新安裝，可以使用 npm ci。這個指令會重新安裝相依套件，鎖定檔不一致時則會停止。

安裝失敗時，先判斷錯誤類別：

現象	檢查方向
網路逾時、連線遭拒	套件來源、Proxy、網路存取情形
Node.js 版本不符	檢查目前終端機使用的版本，而非只看已安裝的版本
檔案使用中、存取遭拒	開發伺服器、編輯器或其他處理程序是否正在使用檔案
鎖定檔與相依套件宣告不一致	是否遺漏相依套件變更，確認後再更新鎖定檔
原生相依套件或平台套件載入失敗	是否從另一台電腦複製了 `node_modules`，應在目前平台安裝

不要將刪除鎖定檔或強制升級相依套件當作通用修正方式。這會同時變更許多相依套件，難以判斷原本的問題是否已解決。

相依套件安裝成功後，執行：

npm run saavo:init

執行順序如下：

建立或保留 .env，補上缺少的 SAAS_SECRET
→ cf-typegen
→ db:migrate:local
→ doctor

這個指令不會覆寫既有的有效主金鑰，也不會建立遠端 Cloudflare 資源。如果在資料庫步驟失敗，前面的 .env 和型別檔案可能已產生。應修正目前的錯誤後繼續，不需要刪除整個專案再重新建立。

初始化後，.env 中的第三方服務驗證資訊仍可能為空。doctor 對 Stripe 或 OAuth 的提示，不能直接解讀為整個應用程式初始化失敗。應先看最終錯誤數，再判斷目前是否需要這項服務。

如果 SAAS_SECRET 已存在但格式錯誤，指令碼不會任意替你更換。新專案應修正為有效設定，已有資料的專案則應先找回原始金鑰，不能直接覆寫。

npm run dev

請一律使用終端機實際顯示的網址和連接埠。專案會依開發伺服器的連接埠產生本機網站網址，不需要因為連接埠變動，就反覆修改 .env 的 VITE_SITE_URL。

最早出現的錯誤	處理方式	驗證結果
找不到模組	完成相依套件安裝，確認未複製其他平台的相依套件目錄	原本的模組錯誤消失
啟動時設定驗證失敗	依錯誤欄位檢查 `config/` 及其參照	可通過 `npm run doctor` 的設定載入
缺少 Binding	核對 `wrangler.jsonc`，必要時執行 `cf-typegen`	執行時可存取對應資源
`no such table`	確認本機資料庫並執行本機遷移	同一頁面不再出現缺少資料表的錯誤
頁面請求傳回 500	搭配請求時間，查看終端機中的例外堆疊	同一請求傳回預期頁面或業務回應

cf-typegen 僅產生型別宣告。編輯器不再顯示錯誤，不代表執行時的 Binding 已存在。也不要將 Cloudflare 資源存取暫時替換為記憶體物件，以掩蓋設定問題。

本機 D1、KV 等狀態與遠端資源彼此獨立。刪除 .wrangler 狀態目錄可能清空本機資料，排錯前應先確認是否需要保留。

專案使用 TypeScript 與 Zod 兩層檢查。常見問題包含產品參照已刪除的角色、聯盟規則參照不存在的方案、時間間隔格式無效，以及將 LocalizedText 寫成一般字串。

先找到錯誤指向的設定項目，再查找它參照的物件。例如，修改產品 ID 後，還要檢查聯盟行銷、頁面和升級建議是否仍使用舊 ID。不要使用 as any 略過驗證。

欄位型別和目前預設值請見設定檔。前面的建置教學可能使用自成體系的範例名稱，移植到自己的專案時，需要統一參照，不能只複製一段設定。

內容更新涉及三個位置：原始檔、建置產生的集合與搜尋索引，以及執行時讀取的 KV 內容。

npm run gen:collections

這一步用來檢查 MDX 能否編譯。出現錯誤時，依檔名和行號檢查 Frontmatter、未閉合的 JSX、程式碼圍欄和元件屬性。導覽未顯示時，再核對 meta.json、語言目錄和 deploy.content 開關。

需要更新搜尋索引時，執行：

npm run gen:search-index

如果目前的問題是內文仍讀取到舊的本機 KV 內容，再執行：

npm run kv:sync:local

以上操作的用途不同，重新產生集合並不能證明遠端 KV 已更新。線上內容問題請見部署、資源與網域。

npm run preview

範本的預覽指令會先執行 build:preview，再使用 127.0.0.1:4173 進行本機預覽。預覽會經過打包流程，不能假設所有行為都與 npm run dev 相同，尤其是郵件寄送、環境變數，以及僅在正式環境模式執行的檢查。

需要單獨定位檢查階段時，執行：

npm run lint
npm run typecheck
npm run build

Vite 可以在未完成完整型別檢查的情況下產生建置檔案，因此建置成功不能取代 typecheck。修正程式碼後，使用 npm run verify 完成專案的全部檢查。

請依結束代碼和實際失敗步驟判斷結果。有些記錄只是警告，但也不要因為最後看到建置檔案清單，就忽略前面出現的型別、內容產生或檔案寫入錯誤。

重新啟動專案，完成原本失敗的頁面操作。如果變更涉及內容，再分別檢查導覽、內文和搜尋。如果變更涉及初始化，再確認原有的本機帳號和資料仍可使用，避免透過清空狀態得到看似成功的結果。