Prisma ORM 8 详细部署与使用教程

Prisma ORM 8 是下一代 Node.js 和 TypeScript ORM，专为现代应用和 AI 智能体时代设计。它提供了一个全新的、可扩展的、对 AI 友好的架构。本教程将指导您完成安装、配置和首次使用。

📋 目录

Prisma ORM 8 是什么
核心特性
系统要求与准备
全新项目快速开始
现有项目迁移安装
AI 智能体集成
核心用法与示例
更新与卸载
常见问题排查

Prisma ORM 8 是什么

Prisma ORM 8 是 Prisma 团队对 ORM 的全面重写，采用 TypeScript 构建。其核心理念是提供一个最小核心、高度可扩展的框架，让开发者（和 AI 智能体）能更高效地处理数据库操作。

核心变化：

TypeScript 原生重写：带来更好的类型安全和性能。
可扩展架构：通过公共 SPI（服务提供者接口），您可以像官方团队一样，轻松添加对新的数据库、查询功能或工具的支持。
AI 智能体优先：内置了针对主流 AI 编码助手（如 Claude Code、Cursor）的技能包（Skills），AI 可以直接学习并使用 Prisma。

核心特性

特性	说明
声明式配置	通过 `prisma.config.ts` 进行单一、类型安全的配置。
合同优先开发	通过 `contract/` 文件定义数据模型和操作，实现类型安全的数据库交互。
可扩展性	官方已提供 `pgvector`（向量搜索）、`postgis`（地理空间）等扩展，您也可以创建自己的扩展。
AI 智能体技能包	内置 `prisma-8` 技能，AI 助手可直接学习并操作 Prisma。
多数据库支持	目前正式支持 PostgreSQL（GA），MongoDB（Early Access）和 SQLite（PoC）。
现代化 CLI	`prisma` CLI 命令统一，支持 `init`、`generate` 等新工作流。

系统要求与准备

Node.js：版本 24 或更新。
包管理器：npm、pnpm 或 yarn（本教程以 npm 为例）。
数据库：推荐 PostgreSQL（正式支持）。也支持 MongoDB（早期访问）和 SQLite（概念验证）。

全新项目快速开始

使用官方交互式脚手架，可以快速创建一个集成了 Prisma ORM 8 的新项目。

1. 运行脚手架命令

1	npm create prisma@next

该命令会引导您：

选择 JavaScript 框架（如 Next.js、Vite、Hono 等）。
选择数据库（PostgreSQL 或 MongoDB）。
自动安装依赖并生成一个可运行的应用示例。

2. 启动应用
脚手架会生成一个包含基础数据模型和查询的示例应用。按照终端提示进入项目目录并启动开发服务器即可。

现有项目迁移安装

如果您想在一个现有项目中引入 Prisma ORM 8，可以使用 init 命令。

1. 在项目根目录运行初始化命令

1	npx @prisma/cli@next orm init

2. 生成的文件
此命令会：

创建 prisma.config.ts 配置文件。
在 src/prisma/ 下生成一个示例 contract/ 文件和 db.ts 客户端。
安装必要的运行时依赖。
注册 AI 智能体技能：在项目根目录生成 prisma-next.md 文件，并为支持的 AI 工具（如 Claude Code、Cursor）安装 SKILL.md 技能文件。

3. 配置数据库连接
编辑 prisma.config.ts 文件，配置您的数据库连接字符串。

AI 智能体集成

Prisma ORM 8 的一大亮点是其对 AI 开发工具的深度集成。安装后，您的 AI 编码助手就能直接获得 Prisma 的操作能力。

对 Claude Code 用户：
安装完成后，Claude Code 会自动加载 .claude/skills/prisma-8/SKILL.md 技能。您可以直接用自然语言下达指令，AI 会理解并执行。

例如：

“添加一个 posts 模型，并与 users 模型建立关联。然后编写一个查询，加载每个用户最近的三篇文章。”

AI 会读取技能文档，了解 Prisma 8 的合同定义和查询语法，并自动生成相应的代码和迁移文件。

技能文件位置：

.claude/skills/<skill-name>/SKILL.md：用于 Claude Code。
.agents/skills/<skill-name>/SKILL.md：用于 Cursor、Copilot Agent 等。

核心用法与示例

1. 定义数据模型（合同）

在 src/prisma/contract/ 目录下定义您的数据模型。例如，user.contract.ts：

import { defineContract } from '@prisma/client'

export const userContract = defineContract({
  // 定义模型和字段
  model: {
    name: 'User',
    fields: {
      id: { type: 'Int', identity: true },
      email: { type: 'String', unique: true },
      name: { type: 'String' },
    },
  },
})

2. 生成客户端代码

在 prisma.config.ts 中配置好后，运行生成命令：

1	npx prisma generate

此命令会根据您的合同定义生成类型安全的数据库客户端。

3. 使用 Prisma 客户端查询

在您的应用代码中（如 src/prisma/db.ts）导入生成的客户端，进行数据库操作。

import { db } from './db'

// 创建用户
const newUser = await db.user.create({
  data: {
    email: 'alice@example.com',
    name: 'Alice',
  },
})

// 查询用户及其关联文章
const userWithPosts = await db.user.findUnique({
  where: { email: 'alice@example.com' },
  include: { posts: true },
})

更新与卸载

更新 Prisma ORM 8

由于是 Next 版本，更新频繁。在项目目录中运行：

1	npx @prisma/cli@next orm update

此命令会更新 CLI、运行时和技能文件。

卸载

由于是开发依赖，直接卸载 npm 包并删除生成的文件即可。

1
2
3

npm uninstall @prisma/client @prisma/cli
# 删除配置文件、合同目录和技能文件
rm -rf prisma.config.ts src/prisma/ .claude .agents/ prisma-next.md

常见问题排查

问题：运行 npm create prisma@next 或 npx @prisma/cli@next 失败。

解决：
1. 确认 Node.js 版本 >= 24。
2. 检查网络连接，确保能访问 npm registry。
3. 清理 npm 缓存：npm cache clean --force。

问题：prisma generate 报错，找不到合同定义。

解决：确保 src/prisma/contract/ 目录下存在有效的 .contract.ts 文件，并且 prisma.config.ts 中的路径配置正确。

问题：AI 助手无法加载 Prisma 技能。

解决：
1. 确认 .claude/ 或 .agents/ 目录下存在 skills/prisma-8/SKILL.md。
2. 重启 AI 助手会话，或检查其技能加载日志。
3. 对于 Claude Code，可在会话中直接输入 @prisma-8 尝试手动触发。

通过以上步骤，您应该能顺利地在项目中引入并使用 Prisma ORM 8。其全新的架构和对 AI 的支持，将极大地提升您的数据库开发体验。如需了解更详细的 API 或高级配置，请查阅项目中的 docs/ 目录或官方博客。