prisma.config.ts 与 .env：配置中心

为什么需要配置文件

v6 时代，数据库连接串写在 Schema 的 datasource 块里。v7 把它移了出来，统一收进 prisma.config.ts。原因是连接信息属于「环境配置」，不该和模型定义混在一起。

这份文件放在项目根目录，用 TypeScript 写，还能享受类型检查。

defineConfig 的基本结构

prisma init 生成的最小配置长这样：

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

逐项解释：

• schema：Schema 文件路径。不写就用默认值 ./prisma/schema.prisma。相对路径是相对配置文件本身解析的，不是相对你敲命令的目录。
• migrations.path：迁移文件存放目录。
• datasource.url：数据库连接串。CLI 跑迁移、建表都靠它。
• datasource.shadowDatabaseUrl：影子数据库（shadow database）连接串。migrate dev 用它检测 Schema 漂移，后面迁移章节会细讲。

defineConfig 是可选的包装函数，也可以直接用 satisfies PrismaConfig 的写法。两者等价，用哪个看个人喜好。

env() 与显式 dotenv

env() 是 prisma/config 导出的辅助函数，做两件事：读环境变量、提供类型安全。

它有个重要行为：变量不存在时直接抛错。比如你跑 prisma generate，配置里 env("DATABASE_URL") 读不到值，就会报：

PrismaConfigEnvError: Missing required environment variable: DATABASE_URL

如果某个环境变量不一定存在（比如 CI 里只跑 generate 不连库），就别用 env()，直接读 process.env：

export default defineConfig({
  datasource: {
    url: process.env.DATABASE_URL ?? "",
  },
});

v7 的另一个大变化：CLI 不再自动加载 .env。必须在配置文件顶部显式 import "dotenv/config"，或用 shell 设置环境变量。Bun 用户例外，Bun 会自动加载 .env。

Schema 里的 datasource 块只剩 provider

连接信息移走后，schema.prisma 的 datasource 块瘦身了：

datasource db {
  provider = "postgresql"
}

原来写在里面的 url、shadowDatabaseUrl、directUrl 都已弃用，全部挪到 prisma.config.ts。Schema 只声明「我用什么数据库」，连接细节归配置文件管。

配置种子脚本

种子数据（Seeding）脚本也在这里注册：

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: "tsx prisma/seed.ts",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

配好后，用 npx prisma db seed 显式执行。注意 v7 里 migrate dev、migrate reset 都不再自动触发种子脚本，要手动跑。

.env 的正确用法

.env 和配置文件是搭档：.env 存值，配置文件读值。几条规矩：

• 永远不提交 .env。prisma init 生成的 .gitignore 已经排除了它。
• 需要多套环境时，拆成 .env.development、.env.production，配合 dotenv-cli 按命令切换：

dotenv -e .env.sample -- npx prisma migrate deploy

• 变量支持展开。.env 里可以引用另一个变量：

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=public

• 配置文件里路径解析的规则：schema、migrations 都相对 prisma.config.ts 的位置。用 npx prisma 时必须在项目根目录执行，否则找不到配置；用 pnpm prisma 则可以从子目录运行。

参考来源

• Prisma 官方文档：prisma.config.ts reference、Upgrade to Prisma ORM v7
• Prisma 官方文档：Environment variables（dev-environment）
• 英文教程：dev.to（Manuj Dixit）- How to Upgrade to Prisma v7
• 英文教程：JS Mastery - Prisma Crash Course for Beginners