prisma/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 [email protected]

崩潰輸出本身會指向此處：--json 崩潰封包會在 nextActions 中攜帶預先填好的指令作為 recover 條目（請直接執行該指令），而人類可讀的崩潰輸出則會以 告訴我們發生了什麼事： 提示結尾。意見回饋是匿名的，除非傳遞了 --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；沒有 branch create/remove 指令）
• 檢查 GitHub/主控台建置日誌與 GitHub 推送即部署狀態
• 使用瀏覽器認證、多個儲存的工作區或 Prisma 服務令牌執行非互動式部署
• 為 @prisma/cli 切換、選取、列出或登出本機 Prisma Platform 工作區
• 使用 @prisma/cli feedback 傳送關於無法解決的 Compute CLI 失敗的意見回饋
• 使用 @prisma/compute-sdk 或 Management API 整合進行程式化部署

決策樹

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

2. 型別化 Compute 設定、單倉庫、部署目標、應用根目錄或建置/環境預設值： 請閱讀 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/cli/state.json 中（如果 prisma.compute.ts 存在，則在其附近）。

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 就緒監視正在監聽的連接埠；僅迴路的監聽者看起來已就緒，但公開的入站流量可能無法到達它。
• runtime-respond-within-60s - 入站流量給予應用 60 秒開始回應，然後回傳 504 閘道逾時 並取消請求。設計處理程式先回答，然後在 waitUntil 或佇列中執行更長時間的工作，絕不能在請求內部執行。

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，對單倉庫或多應用倉庫使用 apps；剛好定義一個。
• config-monorepo-roots - 對於單倉庫，使用 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/主控台的建置輸出。使用 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 - App show/open/logs/list-deploys/promote/rollback/remove 和網域指令也可以接受來自 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()，而不是依賴例外。
• sdk-snapshot-detection - 對未簽出到磁碟的儲存庫快照使用 detectComputeApp；自行列舉工作區，並為每個候選應用根目錄呼叫一次。

偏好工作流程

1. 檢查專案：套件管理器、範本/框架、package.json 腳本、Prisma 版本、Prisma 客戶端位置、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
   • 底層

[此處因原文截斷而截斷]