prisma-orm-setup：把 Prisma ORM 从零跑通的技能

prisma-orm-setup 是什么？

prisma-orm-setup 是 Prisma 生态中的一类 Agent Skill，定位为初始化与配置向导。它不负责你的业务查询逻辑，而是确保 Prisma ORM 在项目中被正确“装上去”。

Prisma ORM 本身是一个下一代 Node.js 和 TypeScript ORM，其设计哲学是声明式 Schema 优先：你在 Prisma Schema（或 Prisma 8 中的 contract）中定义数据模型，Prisma 自动生成类型安全的客户端、管理迁移、并提供可视化数据编辑。

当前 Prisma 有两个活跃的大版本：Prisma 7 仍然完全支持，其配置文件名通常是 prisma7.config.ts；Prisma 8 是当前发布候选版，配置文件名改为 prisma.config.ts，并引入了一些命令重命名（如 contract emit 替代 prisma generate，migration plan 替代 migrate dev）。prisma-orm-setup 的价值在于：让 AI 知道它正在为哪个版本做初始化，避免混用两套命令和配置格式。

prisma-orm-setup 的主要功能

连接配置与驱动适配器。从 Prisma 7 开始，提供驱动适配器是强制性的（不再是可选优化）。这意味着你不能再只写一个 DATABASE_URL 就完事——需要安装对应的适配器包（如 @prisma/adapter-pg 用于 PostgreSQL），并在实例化 PrismaClient 时传入适配器实例。prisma-orm-setup 让 AI 在初始化时就处理这一步，而不是等到运行时报错才补。

项目配置文件生成。Prisma 7/8 将项目配置从 schema.prisma 和 package.json 中剥离，集中到 prisma.config.ts（或 prisma7.config.ts）文件中。这个文件定义 contract 路径、数据库连接方式、以及是否生成 Agent Skill 文件。

数据模型与迁移初始化。从定义第一个模型（如 User）到运行首次迁移、生成客户端、执行第一次查询，prisma-orm-setup 确保每一步的 CLI 命令与当前版本匹配。Prisma 8 中 db init 替代了之前的 db push，contract emit 替代了 prisma generate。

ESM 与运行时兼容。Prisma 7/8 默认以 ES 模块发布。如果你的项目是 CommonJS（如 NestJS 默认），需要在生成器配置中设置 moduleFormat = "cjs"，否则类型导入会失败。Skill 会检查并处理这类兼容性问题。

prisma-orm-setup 的核心特色

版本感知，不混用命令。Prisma 7 和 Prisma 8 的命令名称有显著差异。一个不了解版本差异的 AI 可能会生成 prisma generate（Prisma 7 及以前）或 contract emit（Prisma 8）——两者在不同版本中会报错。prisma-orm-setup 让 AI 先确认版本再执行。

Schema 作为唯一真相源。Prisma 的核心理念是：数据模型只在一个地方定义（schema.prisma 或 contract.prisma），迁移、TypeScript 类型、自动补全、ERD 生成全部由它驱动。prisma-orm-setup 确保 AI 不在代码中重复定义模型类型，而是从生成的客户端导入。

迁移工作流的双轨制。Prisma 明确区分开发和生产环境的迁移命令：开发用 migrate dev（会检测 drift 并提示重置），生产用 migrate deploy（非交互式，使用咨询锁，安全）。AI 在初始化时就应该理解这个边界，而不是在生产环境误用开发命令。

Rust 引擎移除后的新配置需求。Prisma 从 v7 开始移除 Rust 查询引擎，改为 TypeScript/WASM 核心。这带来了约 90% 的包体积缩减和约 3 倍的查询速度提升，但也意味着驱动适配器成为必需。prisma-orm-setup 处理这个转变。

prisma-orm-setup 可以用来做什么？

在新项目中从零初始化 Prisma。安装依赖、创建配置文件、定义第一个模型、运行首次迁移、生成客户端、执行第一次查询。

在已有项目中添加 Prisma。如果项目已有 package.json 和数据库连接，prisma-orm-setup 帮助 AI 以最小侵入的方式接入 Prisma，处理 tsconfig 调整和模块格式兼容。

从现有数据库反向生成 Schema。Prisma 支持数据库内省（introspection），将现有表结构拉取为 Prisma Schema。适合接手已有数据库的项目。

排查初始化失败问题。如果 Prisma 客户端生成失败、迁移命令报错、或 ESM 导入异常，Skill 可以帮助 AI 定位是版本、适配器还是模块格式的问题。

不适合的场景：编写复杂的业务查询逻辑、性能调优（应使用 Prisma Optimize 或数据库原生工具）、从其他 ORM（如 TypeORM、Drizzle）迁移（需要人工规划迁移策略）。

prisma-orm-setup 适合哪些人？

• 首次在 Node.js/TypeScript 项目中引入 ORM 的开发者：不想在版本配置上踩坑。
• 从 Prisma 6 或更早版本升级的用户：需要处理 Rust 引擎移除、驱动适配器强制、配置文件迁移等一系列变化。
• 使用 NestJS 等 CommonJS 框架的团队：需要正确配置 moduleFormat = "cjs" 以避免 ESM 兼容问题。
• 用 AI 编码助手搭建后端项目的开发者：希望 AI 生成的数据库层代码不是“能跑就行”，而是符合 Prisma 当前版本的规范。

不太适合：需要完全手写原生 SQL 的场景、使用非 Node.js 后端的项目、以及不想使用 ORM 抽象层的团队。

prisma-orm-setup 如何安装？

prisma-orm-setup 通常作为 Prisma 项目初始化的一部分被触发，而非独立安装的 Skill 包。安装方式取决于你的 Agent 和 Prisma 版本：

方式一：通过 Prisma CLI 的 Agent Skills 功能（Prisma 8）

Prisma 8 的 init 命令会添加 Agent Skills 文件和一个 postinstall 脚本以保持更新：

npx prisma@latest init

方式二：从 Prisma 官方文档或 GitHub 获取 Skill 文件

Prisma 的文档站点和 GitHub 仓库提供了针对 AI 工具的 Skill 文件。将 SKILL.md 复制到你的 Agent skills 目录（如 Claude Code 的 ~/.claude/skills/ 或项目内的 .claude/skills/）。

方式三：作为 Prisma 项目脚手架的一部分

运行 npm create prisma@latest 或 npx prisma init 时，CLI 可能会提示是否添加 Agent Skill 文件。

prisma-orm-setup 怎么使用？

第一步：让 AI 确认 Prisma 版本。在初始化前，Skill 应该检查项目依赖中是否已有 prisma 包，或询问你要使用 Prisma 7 还是 Prisma 8。两者的配置文件和命令不同。

第二步：安装依赖。

Prisma 7/8 的核心依赖包括：

npm install prisma --save-dev
npm install @prisma/client
npm install @prisma/adapter-pg  # PostgreSQL 适配器，按数据库选择

如果是 Prisma 8，包名有所不同（@prisma/orm-postgres），且 @prisma/client 不再存在。

第三步：创建配置文件。

Prisma 7 使用 prisma7.config.ts，Prisma 8 使用 prisma.config.ts。配置文件指定 contract 路径和数据库连接：

// prisma.config.ts (Prisma 8 示例)
import 'dotenv/config';

export default {
  contract: 'src/prisma/contract.prisma',
  db: { connection: process.env.DATABASE_URL },
  skills: { disabled: true }, // 关闭 Agent Skill 提示
};

第四步：定义数据模型。

在 contract 或 schema 文件中添加第一个模型：

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

第五步：运行迁移和生成客户端。

Prisma 7 的命令：

npx prisma migrate dev --name init
npx prisma generate

Prisma 8 的命令：

npx prisma contract emit
npx prisma db init

第六步：实例化并使用客户端。

import { PrismaClient } from '@prisma/client';
import { PrismaPg } from '@prisma/adapter-pg';

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
const prisma = new PrismaClient({ adapter });

const users = await prisma.user.findMany();

prisma-orm-setup 使用技巧

Prisma 7/8 必须使用驱动适配器。这是从旧版本升级时最容易忽略的变化。只配置 DATABASE_URL 而忘记传适配器实例，客户端会在运行时失败。

在生产环境只用 migrate deploy。migrate dev 可能在检测到 schema drift 时提示重置数据库，这在生产中是灾难性的。migrate deploy 是非交互式的，使用咨询锁防止并发迁移，安全得多。

Serverless 环境不要在每个请求中 $disconnect()。在 AWS Lambda、Vercel 等环境中，容器可能被复用。在每次调用结束时断开连接会浪费连接池的优势。在 handler 外部实例化 PrismaClient，让它随容器生命周期存在。

NestJS 项目必须设置 moduleFormat = "cjs"。Prisma 7/8 默认生成 ESM 模块，与 NestJS 的 CommonJS 设置不兼容。在生成器配置中显式设置：

generator client {
  provider     = "prisma-client"
  output       = "../src/generated/prisma"
  moduleFormat = "cjs"
}

用 select 和 omit 控制返回字段。默认情况下 Prisma 返回模型的所有标量字段。使用 select 白名单或 omit 黑名单来限制返回内容，避免泄露敏感字段或传输不必要的数据。

prisma-orm-setup 收费吗？

Prisma ORM 开源部分免费。Prisma Client、Prisma Migrate 和 Prisma Schema Language 都是开源的。Prisma Studio 是唯一不开源的部分，但可以在本地免费运行。

Prisma 还提供商业化产品：Prisma Accelerate（连接池和全局缓存）和 Prisma Optimize（查询分析），这些按量计费。但基础的 ORM 功能不收费。prisma-orm-setup 作为初始化工具，本身不产生费用。

prisma-orm-setup 的优点与缺点

prisma-orm-setup 与同类工具对比

vs 手动配置 Prisma。手动配置需要查阅当前版本的文档，处理驱动适配器、ESM 配置、配置文件位置等细节。prisma-orm-setup 让 AI 在生成代码时就遵循当前版本的正确模式。

vs TypeORM 初始化。TypeORM 使用装饰器和实体类定义模型，配置更分散（ormconfig 或 DataSource）。Prisma 的 Schema 文件更集中，但需要代码生成步骤。TypeORM 对复杂 SQL 的支持更直接，Prisma 的抽象层更高。

vs Drizzle 初始化。Drizzle 是 SQL-first 的轻量 ORM，Schema 用 TypeScript 定义，零依赖，包体积约 7kb。Prisma 是 Schema-first，包体积在 v7 后显著减小但仍比 Drizzle 大。Drizzle 更接近 SQL，Prisma 更抽象。

vs 不使用 ORM。直接使用数据库驱动（如 pg、mysql2）给完全控制权，但需要手写类型、迁移和查询构建。Prisma 用抽象换生产力和类型安全。

prisma-orm-setup 常见问题 FAQ

Q：Prisma 7 和 Prisma 8 我应该用哪个？
Prisma 8 是当前发布候选版（RC），Prisma 7 仍然完全支持。如果你追求稳定性，用 Prisma 7；如果你想提前适配即将到来的正式版，用 Prisma 8。注意两者命令和配置格式不同。

Q：为什么我的 PrismaClient 实例化报错说需要 adapter？
从 Prisma 7 开始，驱动适配器是强制性的。安装对应数据库的适配器包（如 @prisma/adapter-pg），并在 new PrismaClient({ adapter }) 中传入。

Q：prisma generate 和 contract emit 有什么区别？
它们是同一个操作在不同 Prisma 版本中的名称。Prisma 7 及以前用 prisma generate，Prisma 8 改名为 contract emit。输出都是生成的客户端代码。

Q：NestJS 中 Prisma 导入失败怎么办？
Prisma 7/8 默认输出 ESM 模块。在生成器配置中设置 moduleFormat = "cjs"，强制生成 CommonJS 模块。

Q：Serverless 中每次请求都创建 PrismaClient 可以吗？
不建议。在 handler 外部创建全局实例，让它随容器生命周期复用。每次请求创建新实例会耗尽数据库连接池。

Q：Prisma 支持 MongoDB 吗？
支持。Prisma ORM 支持 PostgreSQL、MySQL、SQLite、MongoDB 以及部分 NewSQL 数据库。

prisma-orm-setup 综合评价

prisma-orm-setup 解决的是一个具体但容易出错的问题：Prisma ORM 在版本演进中改变了初始化约定，而 AI 训练数据往往滞后于最新版本。当 AI 用 Prisma 6 的知识帮你配置 Prisma 7 或 8 项目时，产出的代码可能在 prisma generate 或 new PrismaClient() 处直接失败。

它的价值在版本切换期最为明显。Prisma 7 移除 Rust 引擎、强制驱动适配器、改变配置文件位置、将生成的客户端输出从 node_modules 移到源码目录——这些变化中的任何一个都足以让不熟悉新约定的开发者卡住。prisma-orm-setup 让 AI 在生成初始化代码时就遵循这些新约定。

它的门槛在于版本确认。Prisma 7 和 Prisma 8 的命令名称、配置文件名、包名都有差异。用户需要先明确自己要哪个版本，Skill 才能给出正确的代码。如果你只是模糊地说“帮我装 Prisma”，AI 可能会选择默认的最新版本，但如果你的项目环境或部署目标有版本约束，结果可能不符合预期。

对于正在启动新的 Node.js/TypeScript 后端项目、或计划将现有项目升级到 Prisma 7/8 的开发者，prisma-orm-setup 值得在初始化阶段使用。它不会替你写业务查询，但能确保你的数据库层从一个正确的起点开始。