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 或使用者資料。
真相來源順序
在決定要編輯或執行什麼時，請按此順序使用證據：
- 專案產生的腳本和配置，特別是
prisma.compute.ts、compute:deploy、框架配置和package.json。 - 來自
create-prisma和@prisma/cli的 CLI 幫助輸出。 - 本地已安裝的套件程式碼、產生的建構產物和型別定義。
- 官方文件。
何時套用
在以下情況下使用此技能：
- 建立一個可以部署到 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 Platform 工作區（用於
@prisma/cli） - 使用
@prisma/cli feedback傳送關於無法解決的 Compute CLI 故障的意見回饋 - 使用
@prisma/compute-sdk或 Management API 整合進行程式化部署
決策樹
-
現有專案部署或重新部署： 請參閱
references/app-deploy-cli.md。 -
類型化的 Compute 配置、monorepo、部署目標、應用程式根目錄或建置/環境預設值： 請參閱
references/compute-config.md。 -
特定框架的建置/執行時期工作： 請參閱
references/frameworks.md。 -
從範本建立的新專案： 請參閱
references/create-prisma.md。 -
程式化部署、SDK、API 或底層應用程式/部署概念： 請參閱
references/sdk-api.md。 -
建置、驗證、環境、部署或執行時期故障： 請參閱
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 Gateway Time-out並取消請求。設計處理程序先回應，然後在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- 將可重複使用的部署預設值放在帶有defineComputeConfig的prisma.compute.ts中，而不是放在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分支名稱>。env-production-vs-preview- 對生產環境使用--role production，對預覽範本環境使用--role preview，並對分支特定的覆蓋使用--branch <git分支名稱>。env-db-explicit- 透過資料庫和專案環境指令保持資料庫和環境連接的明確性；部署範例不應新增資料庫設定，且部署不會執行遷移、種子資料或為每個應用程式自動建立一個資料庫。
7. 部署操作
deploy-prod-intent- 僅在使用者意圖進行生產部署時使用--prod --yes。應用程式的首次生產部署會在沒有--prod的情況下自動提升；該旗標用於後續的生產分支部署。deploy-no-promote- 使用app deploy --no-promote進行先建置後驗證：它會建立一個可透過其自己的 URL 存取的候選版本，而不影響線上部署，稍後再使用app promote <部署-id>進行提升。deploy-github-default-branch- 當 Compute 應用程式連接到 GitHub 推送即部署時，合併到預設分支是生產部署路徑；請檢查部署記錄或 GitHub 檢查執行，而不是告訴使用者重新部署合併的 PR 分支或執行預設分支的預覽部署。deploy-build-logs- 使用@prisma/cli build logs <建置-id>取得 GitHub/主控台的建置輸出。使用app logs取得運行時期部署日誌；這兩個 ID 是不同的。deploy-noninteractive-auth- 非互動式部署需要正確的活躍已儲存 OAuth 工作區，或一個支援的服務令牌環境變數；絶對不要列印令牌。deploy-json-for-agents- 對腳本和代理可讀的輸出使用--json --no-interactive。deploy-create-project- 僅在使用者希望部署建立並連結一個新專案時使用--create-project <名稱>；它與--project和PRISMA_PROJECT_ID衝突。deploy-ops-targets- App show/open/logs/list-deploys/promote/rollback/remove 和 domain 指令也可以接受來自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；自行列舉工作區，並對每個候選應用程式根目錄呼叫一次。
偏好工作流程
- 檢查專案：套件管理器、範本/框架、
package.json腳本、Prisma 版本、Prisma Client 位置、prisma.compute.ts和現有的compute:deploy。 - 驗證實際使用中的套件的 CLI 幫助輸出。
- 在進行專案/應用程式修改前驗證身份驗證上下文：
auth whoami --json，以及當可能存在多個本地會話時，執行auth workspace list --json。 - 選擇路徑：
- 現有應用程式部署：當存在時使用配置支援的目標、產生的
compute:deploy，或@prisma/cli app build/run/deploy旗標 - 新應用程式搭建：
create-prisma，然後使用產生的compute:deploy或@prisma/cli app deploy - 低層級
- 現有應用程式部署：當存在時使用配置支援的目標、產生的