07 - Prisma 入门配置指南

Prisma 入门配置指南

本文档记录 Node.js 项目中安装、初始化、首次迁移 Prisma，以及生成 Client 与配置数据库连接的完整步骤。

Step 1：安装 Prisma

在项目根目录终端执行：

cdD:\yunyanshijie\skill_test\nodejsnpminstall@prisma/clientnpminstall-Dprisma

验收：package.json里出现prisma和@prisma/client。

@prisma/client→ dependencies

@prisma/client是运行时依赖：

• 应用启动后，业务代码会import { PrismaClient } from '@prisma/client'并实际调用
• 生产环境（npm install --production或 Docker 构建）需要安装它，否则服务跑不起来
• 它包含连接数据库、执行查询等逻辑，属于应用本体的一部分

因此放在dependencies。

prisma→ devDependencies

prisma是开发/构建时工具（CLI）：

• 主要用途：prisma generate、prisma migrate、prisma db push、prisma studio等
• 这些一般在本地开发、CI 构建、部署前执行，不是 Node 服务处理请求时每次都要跑的
• 生产运行时通常不需要再执行 migrate（多在部署流程里单独跑），也不需要 Studio

因此放在devDependencies。

Step 2：初始化 Prisma（生成 prisma 文件夹）

npx prisma init

会发生什么：

• 新建prisma/schema.prisma
• 新建.env（里面有一条DATABASE_URL=...）

Step 3：配置.env.example和.gitignore

.env.example（新建，可提交 Git）

# 复制为 .env 后填写真实密码 DATABASE_URL="postgresql://postgres:YOUR_PASSWORD@localhost:5432/nodejs_study?schema=public"

.gitignore（新建或追加）

node_modules/ .env

要点：

Step 4：在 package.json 里加便捷脚本（可选但建议）

在"scripts"里追加以下两行：

{"scripts":{"db:migrate":"prisma migrate dev","db:studio":"prisma studio"}}

以后就可以npm run db:migrate，不用记长命令。

db:migrate→prisma migrate dev

作用：根据prisma/schema.prisma同步数据库结构（开发环境用）。

Prisma 会大致做这些事：

1. 对比 schema 和当前数据库，生成迁移文件（在prisma/migrations/）
2. 把变更应用到 PostgreSQL（建表、改字段等）
3. 重新生成 Prisma Client（src/generated/prisma）

例如你现在的 Todo 模型，跑完后会在nodejs_study库里创建Todo表。

典型使用时机：新建/修改 model 后，让数据库和代码定义一致。

db:studio→prisma studio

作用：打开 Prisma 自带的可视化数据库管理界面（浏览器里操作数据）。

会启动本地 Web 服务（一般是http://localhost:5555），在页面上可以：

• 查看表和数据
• 增删改记录（比如手动加一条 Todo）
• 不用写 SQL 或装 pgAdmin

典型使用时机：调试时看数据、手动改几条记录。

Step 5：第一次 migration（在 PostgreSQL 里真正建表）

npmrun db:migrate

提示 migration 名字时输入：init

验收（3 件事）：

1. 终端显示成功（类似database is in sync）
2. 项目里出现prisma/migrations/文件夹
3. 打开 pgAdmin →nodejs_study→ Schemas → public → Tables，能看到Todo表

Step 6：（可选）用 Prisma Studio 看表

npmrun db:studio

浏览器里能看到空的 Todo 表，说明连接正常。

Step 7：生成 Prisma Client

说明：migrate只建表；要在 Node 里查表，还需要生成客户端代码。若 Step 5 已成功执行，migrate dev通常已自动生成；也可单独执行以下命令。

npx prisma generate

验收：出现src/generated/prisma/文件夹。

Step 8：新建src/lib/prisma.ts

这个文件的作用：整个项目共用一个数据库连接（类似 Express 的 app 单例）。

新建文件并写入：

import"dotenv/config";import{PrismaPg}from"@prisma/adapter-pg";import{PrismaClient}from"../generated/prisma/client.ts";constadapter=newPrismaPg({connectionString:process.env.DATABASE_URL,});constprisma=newPrismaClient({adapter});exportdefaultprisma;

说明：Prisma 7 的 import 路径是../generated/prisma/client.ts，不是@prisma/client。这是你schema.prisma里output = "../src/generated/prisma"决定的。

附录：HTTP 状态码