prisma-compute

Prisma Compute

引導代理程式完成 Prisma Compute 應用程式的建立、部署、操作以及特定框架的部署就緒狀態檢查。

Prisma Compute CLI 操作面

使用 Prisma Platform CLI 進行 Compute 應用程式工作流程：

bunx @prisma/cli@latest app deploy --help
bunx @prisma/cli@latest app --help
bunx @prisma/cli@latest build logs --help
bunx create-prisma@latest --help

使用 @prisma/cli@latest 進行 Compute 應用程式部署。使用 create-prisma@latest 建立新專案。

傳送意見回饋與回報 CLI 問題

CLI 內建意見回饋管道。每當指令當機（UNEXPECTED_ERROR）、問題無法透過疑難排解解決，或使用者要求傳送意見回饋給 Prisma 團隊時，請使用此管道：

bunx @prisma/cli@latest feedback "app deploy crashed: <第一行錯誤訊息>"
bunx @prisma/cli@latest feedback "很喜歡部署流程" --email you@example.com

當機輸出會自行導向此處：--json 當機封包會在 nextActions 中攜帶預先填好的指令作為 recover 項目（直接執行即可），而人類可讀的當機輸出則會以 Tell us what happened: 提示結尾。意見回饋是匿名的，除非傳遞 --email，且僅附上 CLI 版本、Node 版本與作業系統平台/架構。切勿在訊息中包含機密資訊、連線 URL 或使用者資料。

真相來源順序

在決定編輯或執行內容時，請依此順序使用證據：

1. 專案產生的腳本與設定檔，特別是 prisma.compute.ts、compute:deploy、框架設定與 package.json。
2. 來自 create-prisma 與 @prisma/cli 的 CLI 說明輸出。
3. 本地安裝的套件程式碼、產生的構件與型別定義。
4. 官方文件。

適用時機

在以下情況使用此技能：

• 建立可部署至 Prisma Compute 的新應用程式
• 將現有 TypeScript 應用程式部署至 Prisma Compute
• 建立或更新型別化的 prisma.compute.ts 部署設定
• 判斷框架是否已準備好部署至 Compute
• 除錯 create-prisma --deploy、compute:deploy 或 app deploy
• 管理 Compute 應用程式日誌、部署、環境變數與網域，以及列出平台分支（branch list；沒有分支建立/刪除指令）
• 檢查 GitHub/Console 建置日誌與 GitHub 推送即部署狀態
• 使用瀏覽器驗證、多個儲存的工作區或 Prisma 服務權杖執行非互動式部署
• 切換、選取、列出或登出本機 Prisma Platform 工作區（適用於 @prisma/cli）
• 使用 @prisma/cli agent install|update|status 安裝或更新 Prisma 技能
• 使用 @prisma/cli feedback 傳送意見回饋或回報無法解決的 CLI 失敗
• 使用 @prisma/compute-sdk 或 Management API 整合進行程式化部署

決策樹

1. 現有專案部署或重新部署：
   請參閱 references/app-deploy-cli.md。

2. 型別化的 Compute 設定、monorepo、部署目標、應用程式根目錄或建置/環境預設值：
   請參閱 references/compute-config.md。

3. 特定框架的建置/執行時期工作：
   請參閱 references/frameworks.md。

4. 從範本建立新專案：
   請參閱 references/create-prisma.md。

5. 程式化部署、SDK、API 或底層應用程式/部署概念：
   請參閱 references/sdk-api.md。

6. 建置、驗證、環境、部署或執行時期失敗：
   請參閱 references/troubleshooting.md。

規則優先順序

優先順序	類別	影響	前綴
1	指令驗證	重大	verify-
2	驗證與工作區選取	重大	auth-
3	框架就緒狀態	重大	framework-
4	執行時期主機與連接埠綁定	重大	runtime-
5	型別化的 Compute 設定	高	config-
6	分支、環境與資料庫連接	高	env-
7	部署操作	高	deploy-
8	SDK 與 API 自動化	中	sdk-

快速規則

1. 指令驗證

• verify-help-first - 使用 CLI 說明輸出確認指令語法。
• verify-prisma-vs-platform-cli - 不要假設 prisma app deploy 存在於 ORM CLI 中；檢查任務是否應使用 @prisma/cli。
• verify-generated-scripts - 若專案已有產生的 compute:deploy 腳本，優先使用。
• verify-public-url - 實際部署後，要求公開部署 URL，不要依賴本機或僅就緒狀態檢查。
• verify-config-support - 將 prisma.compute.ts 視為型別化的 Compute 設定；在編輯或部署前檢查專案的設定與產生的腳本。
• verify-auth-workspace-support - 使用 @prisma/cli auth workspace 指令進行本機工作區的列出/使用/登出流程。

2. 驗證與工作區選取

• auth-source-precedence - 非空的 PRISMA_SERVICE_TOKEN 是指令的有效驗證來源，本機 OAuth 工作區將被忽略。若該變數已設定但為空，CLI 應失敗而非回退至儲存的 OAuth。
• auth-multi-workspace - auth login 可在同一台機器上儲存多個工作區的 OAuth 工作階段。有效工作區指標決定一般指令使用哪個儲存的 OAuth 授權。
• auth-list-before-switch - 使用 auth workspace list --json 檢查本機工作階段。代理程式應優先使用 JSON 中的工作區 ID，因為名稱可能不明確。
• auth-switch-explicitly - 使用 auth workspace use <id-or-name> 進行非互動式切換。僅在互動式選取器或僅有一個本機 OAuth 工作區時，才使用不帶引數的 auth workspace use。
• auth-no-fallthrough - 若有效 OAuth 工作區已登出或重新整理失敗，CLI 不應靜默回退至其他快取的工作區。執行 auth workspace use <id> 選擇下一個工作區。
• auth-single-workspace-logout - 使用 auth workspace logout <id-or-name> 或 auth logout --workspace <id-or-name> 移除一個本機 OAuth 工作區工作階段。單純的 auth logout 會清除所有本機 OAuth 工作區工作階段。
• auth-service-token-switching - 當 PRISMA_SERVICE_TOKEN 已設定時，auth workspace use 不可用，因為服務權杖是有效驗證來源；取消設定該環境變數以切換本機 OAuth 工作區。工作區登出仍僅清除本機 OAuth 狀態。
• auth-storage-awareness - 本機 OAuth 憑證儲存在平台驗證檔案中，工作區中繼資料則儲存在 sidecar 上下文檔案中。專案釘選儲存在 .prisma/local.json 中，CLI 應用程式/專案狀態則儲存在 prisma.compute.ts 附近的 .prisma/cli/state.json 中（若存在）。

3. 框架就緒狀態

• framework-cli-first - 根據 @prisma/cli app deploy 評估部署就緒狀態，而非 create-prisma 能建立的範本。
• framework-supported-cli-deploy - Compute 部署支援 nextjs、nuxt、astro、hono、nestjs、tanstack-start、custom 與 bun。
• framework-create-prisma-defaults-only - create-prisma 可提供產生的預設值與 compute:deploy，但並非現有應用程式的一般部署介面。
• framework-build-output - Compute 需要伺服器進入點或框架構件，而非僅靜態輸出。

4. 執行時期主機與連接埠綁定

• runtime-bind-all-interfaces - 部署的伺服器必須綁定所有介面（0.0.0.0 或框架等效值），而非硬編碼的 localhost 或 127.0.0.1。
• runtime-match-http-port - 應用程式必須監聽部署的 HTTP 連接埠：盡可能讀取 process.env.PORT，或傳遞相符的 --http-port。
• runtime-readiness-port-only - Compute 就緒狀態監控監聽中的連接埠；僅回送監聽器可能顯示就緒，但公開入口無法到達。

5. 型別化的 Compute 設定

• config-optional-simple-app - 部署一般單一應用程式不需要 prisma.compute.ts；若無持久設定，請使用旗標。
• config-init-formalizer - 使用 bunx @prisma/cli@latest init 產生新設定：它會偵測框架、固定名稱/框架/httpPort（以及 Bun/Hono 的進入點），並提供專案連結。--format json 會寫入無相依性的 prisma.compute.json。init 在已有任何設定時拒絕執行，絕不建立程式碼，也絕不部署。
• config-use-prisma-compute-ts - 將可重複使用的部署預設值放在 prisma.compute.ts 中（使用 defineComputeConfig），而非 prisma.config.ts。
• config-app-vs-apps - 單一部署目標使用 app，monorepo 或多應用程式儲存庫使用 apps；僅定義其中一個。
• config-monorepo-roots - 對於 monorepo，使用 prisma.compute.ts 宣告應用程式目標、根目錄、框架預設值、進入點、連接埠與環境變數輸入。
• config-targets - 在多應用程式設定中，@prisma/cli app deploy web 選取 apps.web 目標。若無 [app]，指令可從目前目錄推斷目標；否則 deploy 可執行所有目標，而 build/run 需要一個目標。
• config-region-new-app-only - 設定中的 region 僅作為新建立應用程式的預設值；部署至現有應用程式會保留該應用程式目前的區域。
• config-custom-artifact - 對於預建構或自訂建構的構件，使用 framework: "custom" 搭配 build.outputDirectory 與 build.entrypoint。
• config-no-project-branch-secrets - 不要在 prisma.compute.ts 中提交工作區、專案、分支、生產意圖、服務權杖或機密值；將這些保留在旗標、.prisma/local.json、環境變數儲存或 CI 機密中。應用程式層級的預設值（如 region、root、framework、entry、httpPort 與非機密的環境變數檔案路徑）應放在設定中。
• config-flags-win - 明確的部署旗標（如 --framework、--entry、--http-port、--region 與 --env）會覆蓋設定中的對應值。

6. 分支、環境與資料庫

• env-do-not-leak-secrets - 絕不印出完整的 DATABASE_URL、服務權杖或機密值。
• env-deploy-loads-dotenv - 產生的部署腳本可能透過 prisma.compute.ts 或 --env .env 載入環境變數；在重新部署前檢查實際的腳本/設定。
• env-migrations-separate - 重新部署腳本不會執行遷移或種子資料。請分別執行適當的 Prisma 資料庫腳本。
• env-cli-token-name - @prisma/cli 使用 PRISMA_SERVICE_TOKEN 進行服務權杖驗證。
• env-branch-scope - 分支部署、分支環境變數與分支資料庫必須使用相同的分支名稱；在指定預覽分支時，明確傳遞 --branch <git-name>。
• env-production-vs-preview - 生產環境使用 --role production，預覽範本環境使用 --role preview，分支特定覆蓋使用 --branch <git-name>。
• env-db-explicit - 透過資料庫與專案環境指令明確管理資料庫與環境變數連接；部署範例不應加入資料庫設定，且部署不會執行遷移、種子資料或自動為每個應用程式建立一個資料庫。

7. 部署操作

• deploy-prod-intent - 僅在使用者意圖進行生產部署時使用 --prod --yes。應用程式的首次生產部署會自動提升，無需 --prod；該旗標用於後續生產分支部署的閘門。
• deploy-no-promote - 使用 app deploy --no-promote 進行建置後驗證：它會建立一個可透過自身 URL 存取的候選版本，而不影響線上部署，稍後可使用 app promote <deployment-id> 提升。
• deploy-github-default-branch - 當 Compute 應用程式連線至 GitHub 推送即部署時，合併至預設分支即為生產部署路徑；請檢查部署記錄或 GitHub 檢查執行，而非告訴使用者重新部署已合併的 PR 分支或執行預設分支的預覽部署。
• deploy-build-logs - 使用 @prisma/cli build logs <build-id> 取得 GitHub/Console 建置輸出。使用 app logs 取得執行時期部署日誌；兩者的 ID 不同。
• deploy-noninteractive-auth - 非互動式部署需要正確的有效儲存 OAuth 工作區或支援的服務權杖環境變數；絕不印出權杖。
• deploy-json-for-agents - 對於腳本與代理程式可讀的輸出，使用 --json --no-interactive。
• deploy-create-project - 僅在使用者希望部署建立並連結新專案時使用 --create-project <name>；它與 --project 和 PRISMA_PROJECT_ID 衝突。
• deploy-ops-targets - 應用程式顯示/開啟/日誌/列出部署/提升/回退/移除與網域指令也可接受來自 prisma.compute.ts 的 [app] 目標。
• deploy-report-cli-bugs - 遇到 UNEXPECTED_ERROR 或無法解決的失敗時，使用意見回饋指令回報；請參閱上方的「傳送意見回饋與回報 CLI 問題」。

8. SDK 與 API

• sdk-use-cli-first - 應用程式工作流程優先使用 @prisma/cli app deploy；僅在使用者建立底層自動化時才使用 create-prisma 建立新應用程式。
• sdk-result-handling - @prisma/compute-sdk 回傳 Result 值；檢查 isOk()/isErr() 而非依賴例外。

建議工作流程

1. 檢查專案：套件管理器、範本/框架、package.json 腳本、Prisma 版本、Prisma client 位置、prisma.compute.ts 與現有的 compute:deploy。
2. 驗證實際使用套件的 CLI 說明輸出。
3. 在專案/應用程式變更前驗證驗證上下文：auth whoami --json，若可能有多個本機工作階段，則使用 auth workspace list --json。
4. 選擇路徑：
   • 現有應用程式部署：若存在設定支援的目標、產生的 compute:deploy 或 @prisma/cli app build/run/deploy 旗標
   • 新應用程式範本：create-prisma，然後使用產生的 compute:deploy 或 @prisma/cli app deploy
   • 底層自動化：@prisma/compute-sdk 或 Management API
5. 檢查框架就緒狀態以及主機/連接埠/環境/執行時期需求，包括專案與分支範圍。
6. 在可行時，先執行本機建置或 app build 再部署。
7. 自動化時使用 JSON 輸出部署，然後要求公開 URL 並總結應用程式 URL、應用程式 ID、部署 ID、專案 ID、工作區 ID 與後續步驟。
8. 對於 GitHub/Console 建置，在猜測建置失敗原因前，先檢查 Prisma Compute Deploy 檢查執行或 build logs <build-id>。

避免事項

• 不要將 Compute 部署指引埋入通用的 prisma-cli 技能中。
• 不要為了部署而在現有應用程式內執行 create-prisma；請使用產生的 compute:deploy 腳本或 @prisma/cli app deploy。
• 不要告訴使用者每個 create-prisma 範本都能自動部署。
• 不要使用預設的 DATABASE_URL 值進行部署。
• 不要假設 next start 是 Compute 的執行時期路徑；Next.js 部署需要 standalone 輸出。