Prisma CLI 部署指南:深入解析 `prisma deploy` 命令的完整用法与底层实现
Prisma CLI 部署指南:深入解析 prisma deploy 命令的完整用法与底层实现
prisma deploy 是 Prisma CLI 中最核心的命令之一:每当你在本地修改了 service configuration(尤其是 数据模型 datamodel)中的任何文件后,都必须通过该命令将变更同步到远程 Prisma 服务,驱动数据库 schema 的迁移。读完本文,你将掌握 prisma deploy 的全部命令参数、首次部署时的数据种子(seeding)机制、endpoint 交互式选择的完整流程,以及从源码层面理解部署、迁移轮询、post-deploy 钩子与隐式客户端生成的底层工作原理。
prisma deploy 是什么
prisma deploy 用于部署服务定义(service definition)的变更。Prisma 服务以本地文件为唯一事实来源:数据模型(.graphql SDL 文件)、prisma.yml 中配置的 endpoint、secret、subscriptions、seed、hooks 等共同构成服务的完整定义。每次在本地修改这些文件后,都需要运行 prisma deploy 把这些变更与远程服务同步——服务端会据此计算 schema 迁移步骤并逐步应用到数据库。
在 CLI 的 deploy 命令实现 中,该命令的定义如下:
static topic = 'deploy'
static description = 'Deploy service changes (or new service)'
static group = 'general'
即"部署服务变更(或新服务)",属于 general 命令组。
核心特性概览
- 同步本地变更到远程服务:包括数据模型、订阅、密钥等一切服务定义变更;
- 首次部署自动执行数据种子(seed):若
prisma.yml中提供了seed属性,首次部署会执行数据导入,可通过--no-seed禁用; - 交互式部署目标选择:若
prisma.yml未配置endpoint,命令会提示你交互式选择一个 Prisma 服务器,并将结果写回prisma.yml作为默认部署目标; - 完整的迁移流程:dry-run 预演、迁移步骤轮询、错误与警告处理、部署后钩子与隐式客户端生成。
命令用法与全部 Flags
用法
prisma deploy [flags]
Flags 完整参考
原文档给出的 Flags 如下:
-d, --dry-run Perform a dry-run of the deployment
-e, --env-file ENV-FILE Path to .env file to inject env vars
-f, --force Accept data loss caused by schema changes
-j, --json JSON Output
-w, --watch Watch for changes
--no-seed Disable seed on initial service deploy
而在源码 deploy.ts 中,实际注册的 Flags 更完整,可以对照使用:
| Flag | 短选项 | 类型 | 说明 | 源码位置 |
|---|---|---|---|---|
--force |
-f |
boolean | 接受 schema 变更可能造成的数据丢失 | deploy.ts#L36-L39 |
--new |
-n |
boolean | 强制以交互模式选择集群(源码中内部变量名是 interactive) |
deploy.ts#L40-L43 |
--dry-run |
-d |
boolean | 对部署执行预演(dry-run),不真正应用变更 | deploy.ts#L44-L47 |
--no-seed |
— | boolean | 在首次服务部署时禁用数据种子 | deploy.ts#L48-L50 |
--json |
-j |
boolean | 输出 JSON 格式结果 | deploy.ts#L51-L54 |
--no-migrate |
— | boolean | 禁用迁移(需要 Prisma 1.26+ 服务器) | deploy.ts#L55-L57 |
--env-file |
-e |
string | .env 文件路径,用于注入环境变量 |
deploy.ts#L58-L61 |
--project |
-p |
string | Prisma 定义文件(prisma.yml)的路径 |
deploy.ts#L62-L65 |
--no-generate |
— | boolean | 禁用部署后的隐式客户端生成 | deploy.ts#L66-L68 |
--skip-hooks |
— | boolean | 禁用部署时的 hooks | deploy.ts#L69-L71 |
注:源码中
--new(-n)承担了文档注释里--interactive的角色(new是 JS 保留字,因此内部用interactive变量代替),作用是强制进入交互模式选择集群。此外,--env-file指向的文件路径若不存在,命令会直接报错退出(见 deploy.ts#L86-L88)。
典型示例
部署服务
prisma deploy
部署服务并交互式选择集群作为部署目标
prisma deploy --interactive
使用 .env.prod 中指定的环境变量部署服务
prisma deploy --env-file .env.prod
接受 schema 变更可能造成的数据丢失
prisma deploy --force
源码 help 文本中对 --force 的说明是:从 prisma.yml 部署本地变更到默认服务环境,并"接受 schema 变更可能造成的数据丢失"(deploy.ts#L30-L34)。
首次部署与数据种子(Seeding)
文档明确指出:在服务的第一次部署时,如果 prisma.yml 中的 seed 属性被提供,命令会执行初始数据种子导入;你可以通过传入 --no-seed 选项来阻止这一行为。
seed 属性的两种形态(详见 prisma.yml YAML 结构):
# 方式一:import —— 指向 .graphql 文件(包含 seeding mutations)
seed:
import: database/seed.graphql
# 方式二:import —— 指向 .zip 文件(NDF 规范化数据格式)
seed:
import: database/backup.zip
# 方式三:run —— 执行一条 shell 命令
seed:
run: node script.js
源码层面的执行条件非常明确(deploy.ts#L388-L404):只有 migrationResult.migration 存在、prisma.yml 中定义了 seed、未传 --no-seed 且 projectNew(本次属于首次创建项目) 时,才会调用 this.seed(...) 执行种子逻辑。
种子逻辑由 Seeder 类 实现,其中几个关键校验值得注意:
seed.import与seed.run不能同时提供,否则抛错"Please provider either seed.import or seed.run but not both at the same time"(Seeder.ts#L41-L45);seed.import的源文件必须以.zip或.graphql结尾,且文件必须真实存在(Seeder.ts#L47-L58);- 对于
.graphql文件,Seeder 会用 GraphQL 解析器把文件拆成一个个操作(operation),然后逐个通过client.exec执行(Seeder.ts#L88-L131); - 对于
seed.run,则用cross-spawn以config.cwd为工作目录执行该 shell 命令,退出码非 0 即 reject(Seeder.ts#L146-L169)。
endpoint 缺失时的交互式选择流程
文档说明:如果 prisma.yml 中没有指定 endpoint 属性,命令会提示你交互式选择一个 Prisma 服务器作为部署目标。选定服务器后,它会将结果写入 prisma.yml,成为后续部署的默认目标。若想再次唤起交互提示,只需手动删除 prisma.yml 中的 endpoint 属性即可。
源码流程(deploy.ts#L101-L134):
- 从定义中读取
serviceName(this.definition.service)与stage(this.definition.stage); - 当 serviceName 或 stage 缺失,或传了交互标志(
interactive) 时,触发交互逻辑:await this.env.fetchClusters()拉取可用集群;- 构造 EndpointDialog(
shouldAskForGenerator: false); endpointDialog.getEndpoint()返回用户选定的cluster、workspace、service、stage;- 调用
this.definition.replaceEndpoint(results.endpoint)把 endpoint 写入prisma.yml,随后重新加载定义,并打印Written endpoint \...` to prisma.yml`;
- 否则直接通过
this.definition.getCluster(false)使用配置中已存在的集群。
此外,源码还处理了两类特殊场景:
- 本地集群连通性检查:当选中的集群是本地集群(
cluster.local)且未在线时,抛出 "Could not connect to server at ... Please check if your server is running."(deploy.ts#L136-L140); - 私有集群登录:当集群非本地且为私有(
cluster.isPrivate)时,若没有 workspace、未配置PRISMA_MANAGEMENT_API_SECRET环境变量、也没有 cloud session key,则会触发client.login()登录流程(deploy.ts#L154-L167)。
从源码理解部署的完整执行链路
prisma deploy 并非简单的"上传文件",而是一套完整的"项目存在性检查 → 创建项目 → 部署 → 迁移轮询 → 钩子 → 隐式生成"流水线。以 deploy.ts 为线索,整体链路如下:
1. 参数与配置加载
命令首先解析 flags、校验 --env-file 路径存在,然后 await this.definition.load(this.flags, envFile) 加载 prisma.yml 及其引用的数据模型。若 prisma.yml 缺少 datamodel 属性,命令直接报错:The property datamodel is missing in your prisma.yml(deploy.ts#L95-L99)。
2. 项目存在性检查与创建
projectExists(cluster, serviceName, stage, workspace)通过client.getProject(concatName(...), stage)查询项目是否存在(deploy.ts#L194-L210);- 若不存在,调用
addProject创建:输出 "Creating stage ... for service ...",并通过client.addProject传入 service 的 secrets(deploy.ts#L212-L225),同时把projectNew置为true——这正是后续触发首次种子导入的标志。
3. 部署请求与迁移轮询
this.client.deploy(...) 把服务名、stage、typesString(拼接后的数据模型)、dryRun、订阅(getSubscriptions())、secrets、force、noMigrate 一并发送给服务端(deploy.ts#L252-L261)。
如果迁移包含步骤(migration.revision > 0 且非 dry-run),CLI 会进入迁移轮询循环:
- 每 500ms 调用
client.getMigration(...)查询迁移状态; - 若
migration.errors非空,抛错 "The Migration failed and has not been performed..."(deploy.ts#L282-L288); - 当
applied === steps.length或状态为SUCCESS/ROLLBACK_SUCCESS/ROLLBACK_FAILURE时结束轮询(deploy.ts#L293-L300); - 期间通过
getProgress(applied, of)实时显示(applied/of)进度。
4. 结果打印与错误/警告处理
printResult(deploy.ts#L459-L511)对部署响应做三级处理:
- 有
errors:打印错误并退出(exit code 1),提示"Deployment canceled. Please fix the above errors to continue deploying."; - 有
warnings且未加--force:打印警告并提示使用prisma deploy --force忽略警告,然后退出;加了--force则继续; - 无变更:dry-run 时打印 "There are no changes.",正常部署时打印 "Service is already up to date.";
- 有步骤:打印 "Changes:"(dry-run 时打印 "Potential changes:")及每条迁移消息。
5. post-deploy 钩子
部署成功后,this.definition.getHooks('post-deploy') 取出 prisma.yml 中 hooks.post-deploy 配置的命令列表并逐个执行(deploy.ts#L311-L343),可通过 --skip-hooks 跳过。钩子示例见 prisma.yml 结构文档:
hooks:
post-deploy:
- echo "Deployment finished"
- graphql get-schema --project db
- graphql prepare
6. 隐式客户端生成
从 Prisma 1.31 起,prisma deploy 会在迁移成功后自动执行 prisma generate(deploy.ts#L345-L386)。如果 post-deploy 钩子里还包含 prisma generate 命令,CLI 会打印黄色警告:自 1.31 起客户端已自动生成,无需再通过钩子生成,建议移除相关钩子(deploy.ts#L365-L374)。可通过 --no-generate 禁用隐式生成。
7. 打印 endpoint
最后,printEndpoints 打印部署完成后可用的端点(deploy.ts#L513-L536):
Your Prisma endpoint is live:
HTTP: http://localhost:4466/myservice/dev
WS: ws://localhost:4466/myservice/dev
若服务器版本 ≥ 1.29.0,还会附加 Prisma Admin 的链接。
测试验证
仓库为 deploy 命令提供了测试用例 index.test.ts(当前为 describe.skip 状态),其中两个场景印证了上述行为:
- from empty to default definition:从空定义部署到默认定义,验证首次部署流程;
- to local instance:通过
-n(交互模式)和-c local指定本地集群http://localhost:4466,验证本地集群部署路径。
对应的 mock 响应位于 nocks/default_definition.ts 与 nocks/local_instance.ts,可用于理解部署请求的预期交互格式。
关键实践要点
- 数据模型变更必须部署:每次修改
datamodel指向的.graphql文件后都要运行prisma deploy,服务端会据此生成并应用迁移; - 首次部署会自动 seed:想跳过初始数据填充请加
--no-seed;seed.import与seed.run二选一; - 善用 dry-run 预演:部署前先
prisma deploy --dry-run查看 "Potential changes:",确认无意外破坏后再正式部署; - 数据丢失警告用
--force确认:当 schema 变更可能造成数据丢失时,服务端会返回 warnings 并中止部署,确认后果后使用--force; - endpoint 交互式引导:删掉
prisma.yml里的endpoint(或使用交互标志)即可重新选择部署目标,CLI 会自动把结果写回配置文件; - 不需要重复 generate:Prisma 1.31+ 部署后会自动生成客户端,
post-deploy钩子中无需再手动执行prisma generate; - 环境变量注入:多环境部署(如
.env.prod、.env.dev)通过--env-file注入,与prisma.yml中的${env:VAR}变量机制配合使用,详见 prisma.yml 变量说明。