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: <first error line>"
bunx @prisma/cli@latest feedback "love the deploy flow" --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；没有分支创建/删除命令） - 检查 GitHub/Console 构建日志和 GitHub 推送到部署状态
- 使用浏览器认证、多个已存储的工作区或 Prisma 服务令牌运行非交互式部署
- 切换、选择、列出或登出
@prisma/cli的本地 Prisma Platform 工作区 - 使用
@prisma/cli feedback发送关于无法解决的 Compute CLI 故障的反馈 - 使用
@prisma/compute-sdk或 Management API 集成进行程序化部署
决策树
-
现有项目部署或重新部署： 阅读
references/app-deploy-cli.md。 -
类型化 Compute 配置、单体仓库、部署目标、应用根目录或构建/环境默认值： 阅读
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- 将可重用的部署默认值放在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]时，命令可以从当前目录推断目标；否则部署可以运行所有目标，而构建/运行需要一个目标。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()而不是依赖异常。sdk-snapshot-detection- 对未检出到磁盘的代码仓库快照，使用detectComputeApp；自己枚举工作区，并对每个候选应用根目录调用一次。
首选工作流
- 检查项目：包管理器、模板/框架、
package.json脚本、Prisma 版本、Prisma 客户端位置、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。 - 底层操作：
@prisma/compute-sdk或 Management API。
- 现有应用部署：当存在时使用基于配置的目标、生成的