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；没有创建/删除分支的命令） - 检查 GitHub/Console 构建日志和 GitHub 推送部署状态
- 使用浏览器认证、多个已存储工作空间或 Prisma 服务令牌执行非交互式部署
- 切换、选择、列出或注销
@prisma/cli的本地 Prisma Platform 工作空间 - 使用
@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- 不要假设 ORM CLI 中存在prisma app deploy；检查任务是应该使用@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中，当存在prisma.compute.ts时，CLI 应用/项目状态存储在附近的.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 就绪性检查监听端口；仅回环监听器可能看起来已就绪，但公共入口无法访问它。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-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- 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处理未检出到磁盘的仓库快照；自行枚举工作空间，并对每个候选应用根目录调用一次。
首选工作流
- 检查项目：包管理器、模板/框架、
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 - 底层
- 现有应用部署：使用配置支持的目标（如果存在）、生成的
…
[已截断以进行翻译]