企业官网建设流程全解析

• 后端
• 数据库
• GraphQL

prisma reset是 Prisma CLI 中用于重置当前 stage/cluster 上服务数据的核心命令，适用于开发环境数据清理、测试数据重建以及配合prisma import/prisma export完成数据迁移等场景。本文以 docs/1.2/04-Reference/07-CLI-Command-Reference/02-Data-Workflows/04-prisma-reset.md 为主体，结合 reset 命令源码 与底层 Client.reset 实现，带你完整掌握该命令的用法、Flags、交互确认机制与底层工作原理。

命令概述

prisma reset用于重置（清空）当前 stage/cluster上的服务数据。这里的"当前"由项目根目录下的服务定义文件prisma.yml决定——CLI 会读取该文件中的service、stage、cluster等配置，确定要操作的具体服务实例。

从源码看，该命令在 reset.ts 中被定义为：

static topic = 'reset' static description = 'Reset the stage data' static group = 'general'

即其命令主题为reset，描述为"重置 stage 数据"，归属于general命令组。

典型使用场景

• 开发环境数据重建：每次开发迭代前清空数据库，重新导入种子数据；
• 测试数据隔离：在 CI 或本地测试中，先重置再灌入确定的测试数据集，保证测试可重复；
• 配合数据迁移工作流：先用prisma export备份数据，prisma reset清空目标环境，再通过prisma import恢复，实现环境间数据搬运。

⚠️ 注意：prisma reset会永久删除当前服务实例中的数据，操作不可逆。执行前请务必确认目标 stage/cluster，必要时先用 prisma export 做好数据备份。

用法与 Flags

基本用法

prisma reset [flags]

Flags 一览

原文档给出的两个核心 Flags：

-e, --env-file ENV-FILE Path to .env file to inject env vars -f, --force Force reset data without confirmation

此外，从 reset.ts 的 Flags 定义中还可以看到一个在官方文档中未列出的隐藏 Flag：

-p, --project PATH Path to Prisma definition file

--project用于显式指定 Prisma 服务定义文件（prisma.yml）的路径，方便在非标准目录结构或需要针对不同定义文件执行操作时使用。

--env-file的作用

prisma.yml中经常通过${env:XXX}语法引用环境变量，例如：

service: example stage: ${env:PRISMA_STAGE} cluster: ${env:PRISMA_CLUSTER} secret: ${env:PRISMA_SECRET} datamodel: database/datamodel.graphql

此时--env-file指定的文件会先被加载、注入环境变量，再加载prisma.yml（对应源码中的this.definition.load(this.flags, envFile)）。根据 Using Variables 文档，CLI 加载环境变量的顺序为：本地环境 →--env-file指定的文件 → 默认的.env文件。关于prisma.yml的完整结构，可参考 prisma.yml 概览与示例。

实战示例

带确认提示的重置

prisma reset

执行后会先根据prisma.yml定位当前服务与 stage，然后弹出交互式确认。确认提示的文案在源码中定义为（见 reset.ts）：

Are you sure that you want to reset the data of <serviceName> in stage <stage>? y/N

默认值为n，即默认拒绝。输入y（不区分大小写、以y开头即可）才会继续执行重置；输入n或其他以n开头的回答，命令会直接以退出码 0 结束，不做任何操作。这一默认安全策略避免了误触导致的不可逆数据丢失。

跳过确认强制重置

prisma reset --force

或使用短形式：

prisma reset -f

该命令适用于脚本化、CI 等无人工干预的场景。由于跳过了确认环节，务必确认目标 stage/cluster 正确后再执行。

源码级工作原理

理解prisma reset的完整调用链，有助于你判断它在各种环境下的行为。

命令执行流程（reset.ts）

run()方法的执行顺序如下（对应 reset.ts）：

1. 读取--force与--env-file两个 Flag；
2. 调用this.definition.load(this.flags, envFile)加载服务定义（prisma.yml），并解析出serviceName与stage；
3. 通过this.definition.getCluster()获取当前 cluster，并将其设为活动 cluster；
4. 若未加--force，调用askForConfirmation(serviceName, stage)进行交互确认；
5. 调用this.reset(serviceName, stage)真正执行重置。

执行重置时，命令会向用户展示进度提示Resetting <serviceName>@<stageName>，并在结束后输出耗时（单位毫秒），对应源码：

this.out.action.start(`Resetting ${chalk.bold(`${serviceName}@${stageName}`)}`) await this.client.reset(...) this.out.action.stop(chalk.cyan(`${Date.now() - before}ms`))

底层 API 调用（Client.ts）

重置动作最终由 CLI 引擎的 HTTP 客户端完成。在 Client.ts 中，reset方法向Prisma API 的/private端点发送一次POST请求，请求体是一个 GraphQL mutation：

mutation { resetData }

关键实现细节：

• 请求地址：this.env.activeCluster.getApiEndpoint(serviceName, stage, workspaceSlug) + '/private'，即当前活动 cluster 的 API 端点拼接/private路径；
• 鉴权：请求头携带Authorization: Bearer <token>，token 来自this.definition.getToken(serviceName, stageName)；若服务属于某个 workspace，还会传入getWorkspace()的值用于定位端点；
• 代理支持：请求通过getProxyAgent(endpoint)挂载代理，在企业网络环境下同样可用。

这一设计说明：prisma reset并非直接操作本地数据库，而是向运行中的 Prisma 服务发送 GraphQL mutation，由服务端完成数据清空，因此目标 cluster 必须处于可访问状态。

相关命令与数据工作流

prisma reset属于 CLI 命令参考中的Data Workflows（数据工作流）分组，与它同组的是 prisma import、prisma export 和 prisma playground，完整列表见 CLI 命令参考索引。

在实际开发中，prisma reset常与以下命令组合使用：

值得留意的是，从 seed 命令源码 可以看到，prisma seed自身也接收一个reset布尔标志（const { reset } = this.flags），并在执行播种时把 stage 与 reset 标志一并传递，可以推断出"先重置、再播种"的原子化操作在该版本中同样被支持，适用于一键重建带种子数据的环境。

注意事项与最佳实践

1. 数据不可逆：重置即永久删除，无法通过命令撤销；重要数据务必先prisma export备份；
2. 确认目标环境：--force会跳过一切确认，脚本中执行时建议通过环境变量区分 stage（如stage: ${env:PRISMA_STAGE}），避免误操作生产环境；
3. 鉴权要求：重置请求需要携带有效的服务 token，确保prisma.yml中的secret配置与 cluster 端一致；
4. cluster 可达性：命令通过 HTTP 调用目标 cluster 的/private端点，需保证网络连通与代理配置正确；
5. 优先交互模式：本地手动操作时建议不加--force，利用默认y/N（默认拒绝）的安全机制作为最后一道防线。

• 后端
• 数据库
• GraphQL