如何為你的應用程式建置預備環境（Staging）

要建置預備環境，請將應用程式的第二份副本部署到它自己的私有網址，為它設定獨立的資料庫與測試用 API 金鑰，並盡可能讓它的設定與正式環境一致。接著，每一項重要變更都先發布到預備環境，走過重要的流程，確認預備環境一切正常後，才發布到正式環境。

如果你還不熟悉這個概念，請先閱讀什麼是預備環境。本指南是實作上的設定說明，適合使用 AI 工具建置應用程式、而非經營 DevOps 團隊的人。

開發、預備與正式環境

大多數小型應用程式至少需要三個環境，即使第一個只是你的建置工具所提供的預覽：

預備環境的重點在於它的行為必須與正式環境相同：相同的程式碼、相同的技術堆疊、相同類型的設定，但在那裡犯的錯誤不會傷害任何人。

步驟一：決定預備環境必須與什麼一致

只有當問題在正式環境出現之前就先在預備環境中暴露出來，預備環境才有價值。請讓以下項目保持一致：

• 相同的程式碼，並以相同的方式發布。
• 相同的技術堆疊與版本，包括框架、執行環境與資料庫類型。
• 相同類型的設定，即相同的環境變數名稱，但使用測試值。
• 相同的服務：如果正式環境同時有網頁應用程式與 API，預備環境也應該兩者都有。

兩者可以在規模（使用較小的機器也沒問題）與資料上有所不同。

步驟二：建立副本

最簡單的做法是：為同一個專案再部署一次，使用不同的網址，例如 staging.yourapp.com 或 yourapp-staging.example.com。

具體做法取決於你的主機：

• 內建預覽或預備部署功能的主機：可以為 Git 分支自動建立預備環境。
• 沒有此功能的主機：使用同一份程式碼建立第二個應用程式或專案，並分別部署。
• 程式碼存放於 Git：保留一個 staging 或 main 分支並部署到預備環境，正式環境則從發行版本部署。請參閱如何在 AI 建置的應用程式中使用 Git。

步驟三：讓預備環境擁有獨立的資料庫

這一步能保護你。如果預備環境與正式環境共用資料庫，一個會刪除紀錄的測試，就會刪除真實的紀錄。

• 為預備環境建立獨立的資料庫。
• 以種子資料填入資料庫，也就是 AI 能幫你產生的、貼近真實的假資料。
• 如果你需要正式環境資料的副本，請先移除或打亂姓名、電子郵件以及任何個人資訊。

撰寫一個種子腳本，為空白的資料庫填入貼近真實的測試資料：20 位客戶、50 筆處於不同狀態的訂單，以及兩位管理員使用者。姓名請明顯使用假名，電子郵件請使用 example.com 網域。

在你信任這項設定之前，請確認每一份副本各自連接到哪個資料庫。可以直接詢問：

這個應用程式連接到哪個資料庫？這個設定來自哪裡？請顯示變數名稱，不要顯示密碼。

步驟四：使用測試金鑰與獨立設定

所有與外部服務溝通的項目，在預備環境中都應使用測試憑證：

• 付款使用測試模式（例如 Stripe 的測試金鑰），確保不會真的扣款。
• 電子郵件寄送到沙盒環境，或只寄給你自己的地址，確保客戶永遠不會收到測試郵件。
• AI 與其他付費 API使用獨立的金鑰，並設定較低的消費上限。
• Webhook指向預備環境的網址，而非正式環境。

兩個環境中的變數名稱應保持相同，只更改其值。這樣程式碼就不需要知道自己正在哪個環境中執行。若想進一步了解，請參閱如何安全保管 API 金鑰。

步驟五：讓預備環境保持私密

預備環境不應該公開：

• 將它放在登入、密碼，或團隊電子郵件白名單之後。
• 使用 noindex meta 標籤或 X-Robots-Tag 標頭，阻止搜尋引擎建立索引。
• 不要從你的公開網站連結到它。
• 讓它的外觀與正式環境不同：例如加上一條有顏色的「STAGING」橫幅，避免在錯誤的分頁中進行測試。

當 APP_ENV 環境變數為 "staging" 時，在每一頁的頂部加上一條醒目的黃色橫幅，寫著「STAGING — 僅限測試資料」。同時在這種情況下加上 noindex meta 標籤。

步驟六：建立發布流程

預備環境只有在你每次都使用它時才有幫助。一個簡單的流程如下：

1. 在開發環境中做出變更，並在預覽中檢查。
2. 將變更發布到預備環境。
3. 走過你的關鍵流程：註冊、登入、主要功能、付款，以及此次變更所涉及的任何部分。
4. 若有任何問題，修正後再次發布到預備環境。
5. 將相同的版本發布到正式環境。
6. 快速檢查正式環境，走過同樣的流程，時間簡短即可。

請把關鍵流程寫成一份簡短的測試腳本。關於應該包含哪些內容，請參閱如何在上線前測試你的應用程式。

步驟七：謹慎處理資料庫變更

資料庫結構的變更（例如新增欄位、重新命名資料表）正是預備環境最能發揮價值的地方。

• 每一項結構性變更都先在預備環境執行。
• 檢查既有資料是否完好無損，而不只是確認新功能可以運作。
• 在正式環境執行相同的變更之前，先備份正式環境的資料。請參閱如何備份你的應用程式資料庫。
• 優先採用新增而非重新命名或刪除的變更，如此一來，若需要回滾，舊版本仍能正常運作。

提示詞範例

如果我們在正式環境執行這項資料庫變更，現有資料會發生什麼事？有任何資料被刪除或重新命名嗎？

將所有與環境相關的設定（API 網址、金鑰、郵件寄件者、網站自身的網址）改為從環境變數讀取，並在預備環境與正式環境中使用相同的變數名稱。請列出這些變數。

根據這個應用程式的功能，請撰寫一份簡短的清單，列出每次發布前我應該在預備環境中測試的流程。

常見錯誤

• **共用資料庫。**這是最具破壞性的錯誤。預備環境一定要有自己的資料庫。
• **在預備環境使用正式金鑰。**會造成真實的扣款，並寄出真實的郵件給真實的客戶。
• **預備環境與正式環境逐漸脫節。**版本或設定不同，預備環境就無法再發現問題。
• 公開且被建立索引的預備網站，與你的正式網站一起出現在搜尋結果中。
• **因為是「小」變更而跳過預備環境。**小變更也會造成問題。
• **在錯誤的分頁中測試。**一條醒目的橫幅就能解決。

檢查清單

• 預備環境與正式環境執行相同的程式碼、技術堆疊與服務。
• 預備環境擁有獨立的資料庫，並使用測試資料或已清理的資料。
• 付款、電子郵件與付費 API 在預備環境中使用測試金鑰。
• 各環境的變數名稱一致，只有值不同。
• 預備環境受登入或密碼保護，且未被建立索引。
• 身處預備環境時會顯示橫幅。
• 每次發布都先送到預備環境，並附上書面的待檢查流程清單。
• 資料庫變更先在預備環境執行，發布前已備份正式環境資料。

在 Mythex 上使用預備環境

Mythex 的發布功能為每個應用程式提供一個正式網址；沒有獨立的預備環境開關。實務上，你有兩種選擇：

• 以預覽作為發布前的檢查。每個專案都在私有雲端工作區中運行，並提供即時預覽。/test 能讓代理程式像一般用戶一樣在預覽中操作，而分享連結則讓客戶或團隊成員審閱預覽，無需發布。請參閱預覽與程式碼。對許多獨立開發的專案來說，這已經足夠。
• **以第二個專案作為預備環境。**在 Pro 方案中，你可以匯出專案，再匯入到新的專案中，為該專案設定獨立的資料庫與測試金鑰機密資訊，並以它自己的 slug 發布。在發布正式專案之前，先發布到這個預備專案。

無論採用哪種方式，在進行任何具破壞性的測試之前，都請先詢問代理程式預覽與已發布的應用程式分別使用哪個資料庫，並使用檢查點在出現錯誤變更時回滾。若想更全面地了解如何讓應用程式正式上線，請參閱如何將 AI 原型推進到正式環境。

常見問題