环境准备与第一个项目（10 分钟上手）

检查版本：Node 与 TypeScript

Prisma v7 对运行环境有硬性要求：

• Node.js：^20.19.0、^22.12.0 或 ^24.0.0，推荐 22.x LTS
• TypeScript：5.4 以上，推荐 5.9.x

先确认你的版本：

node --version   # 应输出 v20.19.0 或更高
npm --version
tsc --version    # 如果全局没装 TypeScript，这步可跳过

版本不够会怎样？npm install 时若 Node 版本过低会提示 engines 不满足，直接升级 Node 到 20.19+ 即可。升级 Node 最简单的方式是从 nodejs.org 下载 LTS 安装包，或用 fnm、nvm 这类版本管理器。

创建项目与安装依赖

mkdir hello-prisma
cd hello-prisma
npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

接着安装 Prisma 全家桶。注意分成两组：prisma 是 CLI，只在开发时用；@prisma/client 是运行时依赖：

npm install prisma @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

每个包的职责：

• prisma：命令行工具，跑 init、migrate、generate
• @prisma/client：查询数据库的客户端库
• @prisma/adapter-pg + pg：驱动程序适配器（Driver Adapter）。v7 强制要求，Prisma 通过它连接 PostgreSQL
• @types/pg：pg 的类型定义
• dotenv：从 .env 加载环境变量

配置 ESM

Prisma v7 只发布 ES Module，项目必须声明 ESM。在 package.json 里加一行：

{
  "type": "module"
}

tsconfig.json 同步调整：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true
  }
}

module: "ESNext" 启用 import 语法，strict 打开严格模式。这样配置后，代码里写 import 而不是 require。

初始化与建表

npx prisma init --datasource-provider postgresql --output ../generated/prisma

这条命令生成 prisma/schema.prisma、prisma.config.ts、.env、.gitignore 四个文件。把数据库连接串填进 .env：

DATABASE_URL="postgresql://用户名:密码@localhost:5432/数据库名?schema=public"

在 schema.prisma 里定义两个模型（模型的概念下一章细讲，先照抄）：

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

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User    @relation(fields: [authorId], references: [id])
  authorId  Int
}

然后把模型变成真实的数据库表：

npx prisma migrate dev --name init
npx prisma generate

实例化客户端（骨架）

新建 lib/prisma.ts，实例化带适配器的客户端。这是每个 Prisma 项目的固定骨架：

import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../generated/prisma/client";

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

export { prisma };

第一个查询怎么写，见第 5 章。

轻量路线：SQLite

不想装 PostgreSQL？换 SQLite，连数据库服务器都不用，数据就存一个本地文件。

npm install @prisma/adapter-better-sqlite3
npx prisma init --datasource-provider sqlite --output ../generated/prisma

.env 改成文件路径：

DATABASE_URL="file:./dev.db"

实例化时换成对应的适配器：

import "dotenv/config";
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";
import { PrismaClient } from "../generated/prisma/client";

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

export { prisma };

其余步骤完全一样：定义模型、migrate dev、generate，第一个查询见第 5 章。SQLite 适合练习和原型，正式项目大多还是用 PostgreSQL 这类服务器数据库。

参考来源

• Prisma 官方文档：Quickstart（PostgreSQL、SQLite）
• Prisma 官方文档：System requirements（版本要求）
• 英文教程：JS Mastery - Prisma Crash Course for Beginners
• 英文教程：Tech Insider - Prisma ORM Tutorial（TypeScript + PostgreSQL）