PAYATHON 2026

NestJS 与 Prisma 8 的 TypeScript 模块迁移运行方式

数据小陈

结论:不需要为了跑一个 Prisma 迁移脚本,把整个 NestJS 项目的 package.json 的 type 临时改成 module。更稳妥的做法是保持 NestJS 当前模块模式不变,让迁移脚本通过独立的 TS 运行器、独立包边界或 Prisma CLI 来执行。

为什么不建议直接改全局 type

package.json 的 type 会影响整个包内 .js 文件的解释方式,也会影响 NodeNext 下 TS 编译产物的模块解析。只为一个迁移文件切换它,容易把 Nest CLI、Jest、配置文件和 Prisma Client 的导入方式一起带偏。真正要确认的是迁移运行器需要 CommonJS 还是 ESM,先别假设 NestJS 必须采用某种模式。

推荐做法

  1. 优先用 Prisma CLI 管理迁移。如果只是常规数据库迁移,先确认 Prisma 8 对应的迁移命令,例如:
npx prisma migrate dev --name init

不要因为存在一个 TS 迁移文件,就绕过 Prisma CLI 直接 node 执行 TS。Prisma 8 是否支持或要求某种 TS migration 运行方式,要以对应版本文档和实际报错为准。

  1. 需要执行自定义 TS 脚本时,用 tsx 或 ts-node 指定模块模式,不要改全局 type。例如:
npx tsx migrations/app/\<migration label\>/migration.ts

或显式按 CommonJS 编译运行:

npx ts-node --compiler-options '{"module":"CommonJS"}' migrations/app/\<migration label\>/migration.ts

这类方式只影响该次执行,不会改变 NestJS 主应用的模块设置。

  1. 如果迁移脚本确实只能是 CommonJS,用包边界隔离它。例如在迁移目录放一个独立的 package.json:
{
  "type": "commonjs"
}

或者把迁移入口写成 .cts,让该文件按 CommonJS 处理:

npx tsx migrations/app/\<migration label\>/migration.cts

这比把根目录 package.json 改成 module 更可控。

  1. 必要时先编译再运行。对 CI 或生产环境,可以固定输出到临时目录:
npx tsc migrations/app/\<migration label\>/migration.ts --module commonjs --outDir .migration-dist --esModuleInterop
node .migration-dist/migration.js

注意事项

  • 先确认报错来自 Prisma CLI、Prisma Client 还是你自己写的迁移入口;不同来源的处理方式不同。
  • Node 原生执行 .ts 的能力与 Node 版本和实验特性有关,团队项目里更建议用 tsx、ts-node 或 tsc 固定流程。
  • 如果使用 monorepo/workspace,给迁移工具单独建包并声明自己的模块类型,是最干净的“按边界处理”方式。
  • 不建议为了一个命令长期维护两套互相冲突的 tsconfig;只给迁移入口做局部覆盖即可。

备注:内容仅供参考。