部署至 Mastra platform

mastra deploy 是將 Mastra 應用程式發佈至 Mastra platform 的單一指令。

此指令會在納入任何內容前建置並驗證專案；第一次執行時也會建立 platform 專案與環境、進行部署、串流建置記錄，並在部署開始提供流量服務後列出公開 URL。

mastra deploy

備註

本頁說明統一部署流程。先前分開的指令 mastra server deploy 與 mastra studio deploy 仍然可用，但建議使用 mastra deploy。

開始之前

你需要一個 Mastra 應用程式及 Mastra platform 帳戶。如果尚未驗證身分，CLI 會在第一次使用時提示你登入。

本機 .env 檔案並非必要。部署時會直接使用儲存在 platform 上的環境變數，託管資料庫等受管理資源也會注入自己的變數。只有想在其上疊加本機值時，才需傳入 --env-file。

第一次部署

1. 在專案目錄中執行：

   mastra deploy

   第一次執行時，CLI 會提示你建立 platform 專案（以 package.json 命名）與 production 環境。接受提示，或傳入 --yes 直接接受預設值而不確認。

2. CLI 會在發佈任何內容前執行部署前檢查。若儲存空間會回退至本機檔案路徑（在 platform 的暫時性檔案系統中無法留存），通常會阻擋部署：

   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set

   CLI 不會直接回報錯誤，而會讓你就地修正：

   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)

   接受提示後，佈建只需幾秒；資料庫連線變數會自動注入部署，完全不必複製至 .env 檔案。若拒絕，或在非互動式 shell（CI、--yes）中執行，CLI 會回復先前的行為：列出要自行執行的確切指令。

   mastra env db create production --kind turso

   環境 slug（上述 production）會符合 CLI 原本要部署的環境。這一點很重要，因為專案有多個環境時，在非互動式 shell 中執行 mastra env db create 必須提供環境引數。

   備註

   如果部署前檢查回報的是硬式編碼的本機路徑（Build contains a host-local storage URL），便無法提供就地修正。請先以環境變數保護路徑，讓該檔案只在本機開發期間使用：

   src/mastra/index.ts

   new LibSQLStore({
     id: 'mastra-storage',
     // Uses the hosted database when deployed, a local file during development
     url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
     authToken: process.env.TURSO_AUTH_TOKEN,
   })

3. 再次執行 mastra deploy。通過部署前檢查後，建置會上傳，CLI 也會持續串流建置記錄，直到部署上線。完整建置和部署預計需時 30 秒至數分鐘。只有新版本開始提供流量服務後，才會列出成功訊息。

4. 使用 CLI 列出的 URL 驗證部署。附加 /api/agents，確認它會傳回 Agent 的 JSON 清單。

   警告

   對外公開端點前，請先設定驗證。

第一次部署會寫入 .mastra-project.json 檔案，將你的目錄連結至 platform 專案。請提交此檔案，讓後續部署、CI 執行及 mastra env 指令不必提供額外旗標，也能指向同一專案。

部署至其他環境

mastra deploy 預設以 production 環境為目標。傳入 --env 可指定其他環境。如果環境尚不存在，CLI 會提示你建立：

mastra deploy --env staging

每個環境都有各自的 URL 與環境變數，也可以擁有自己的託管資料庫。

如需完整模型，請參閱環境。

選擇區域

部署建立新環境時，傳入 --region 可控制執行位置。請使用 us 或 eu 簡寫：

mastra deploy --env production --region eu

區域會在建立環境時固定。附加至環境的資料庫會自動放在靠近該環境區域的位置，可觀測性資料則會路由至符合環境資料駐留區域的擷取區域。如需支援區域、資料庫位置及可觀測性共置的完整清單，請參閱區域。

部署前檢查

部署前檢查會在納入任何內容前驗證建置輸出，且只會標示自有程式碼中的問題：

• 本機儲存路徑：會直接阻擋。每次部署都會遺失檔案型儲存空間（例如 file:./mastra.db）。若路徑由環境變數保護，且該變數已在本機設定、儲存於 platform，或由受管理資料庫提供，即可通過部署前檢查：

  src/mastra/storage.ts

  import { LibSQLStore } from '@mastra/libsql'
  
  export const storage = new LibSQLStore({
    id: 'mastra-storage',
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })

• 缺少環境變數：程式碼讀取的變數沒有任何來源提供時會顯示警告。只由程式庫程式碼參照的變數不包含在內。

遇到部署前檢查阻擋時，建議修正原因，通常是附加託管資料庫或將變數儲存至 platform。--skip-preflight 是緊急避用選項，但會略過用於防止部署失敗的檢查。

執行檢查但不部署：

mastra lint --preflight

mastra lint 只能讀取本機環境檔案，無法得知儲存在 platform 或由受管理資料庫注入的變數。因此，即使 lint 仍回報錯誤，部署仍可能通過部署前檢查。

環境變數

部署會從三個來源解析環境變數：

• 受管理變數：由託管資料庫等 platform 資源注入（例如 TURSO_DATABASE_URL）。這些變數由 platform 定義，無法編輯。
• 已儲存變數：透過控制面板儲存在專案或環境中。每次部署都會直接使用，不需要本機檔案。
• 本機環境檔案：部署會在其上疊加明確指定的 --env-file，或目前的 .env 與 .env.local 檔案。

mastra deploy --env staging --env-file .env.staging

若要變更執行中服務的變數而不重新部署，請在控制面板更新後執行 mastra env restart。

專案解析

每次部署都會依下列順序解析目標專案：

1. MASTRA_PROJECT_ID 環境變數
2. --project <name|slug|id> 旗標
3. 目前目錄中的 .mastra-project.json 檔案

在 CI 中，請設定 MASTRA_PROJECT_ID 和 MASTRA_API_TOKEN，並傳入 --yes：

mastra deploy --env production --yes

相關內容

• 環境
• 區域
• 託管資料庫
• mastra deploy CLI 參考
• 設定