NestJS 12.0.0 在 2026 年 8 月 27 日正式发布。

单看更新日志，列出的东西不算少：ESM、Standard Schema、重新改造的 CLI，还有一个叫 @nestjs/observe 的新包。

如果光看这些名字，很多人大概会觉得又是一次例行升级。

但翻完官方发布说明和迁移指南后，我觉得这次升级真正有意思的地方，不在 Controller、Service 或依赖注入这些日常写法上。

这些 NestJS 最核心的东西基本没怎么动。

真正大换血的，是它底下那整套 Node.js 工程工具链。

过去几年，Node.js 社区在模块规范、构建工具、测试框架和代码检查工具上已经经历了几轮更迭。NestJS 12 更像是趁着这次大版本，把这些变化正式吸收进自己的默认工程体系。

官方核心包切到 ESM，老项目先别慌

NestJS 12 最基础的一项变化，是核心包全面转向 ESM。

包括 @nestjs/core、@nestjs/common 在内的核心包，现在都以 ESM 形式发布，package.json 中也已经明确设置：

json

{
  "type": "module"
}

从框架自己的发布产物来看，CommonJS 已经不再是默认方向。

很多维护老项目的同学看到这里可能会头皮发麻。

毕竟过去几年 Node.js 社区被 ESM 迁移折腾得够呛，谁也不想为了升一个 NestJS 大版本，顺手再把一个运行了几年的业务项目全部重构一遍。

好在 NestJS 这次没有要求大家一起梭哈。

官方明确说明：

现有 CommonJS 项目可以继续使用 NestJS 12。

原因在于新版 Node.js 已经支持通过 require() 加载 ESM 模块。

也就是说，NestJS 自己可以变成 ESM，而你的业务代码依然暂时保持 CommonJS：

text

NestJS 核心包
    ↓
   ESM

业务项目
    ↓
CommonJS

两边并不要求一次完成迁移。

这也是为什么 NestJS 12 对 Node.js 版本提出了新的最低要求。

运行 NestJS 12 应用，至少需要 Node.js 20.19，或者 Node.js 22.x 中的 22.12 及以上版本。

不过这里还有一个很容易忽略的区别：

运行 NestJS 应用和运行最新版 CLI 的版本要求，并不完全一样。

应用本身可以运行在 Node.js 20.19+，但 nest new、nest generate、nest upgrade 这些依赖最新 schematics 的 CLI 操作，要求会更高，目前需要 Node.js 22.22.3+、24.15+ 或 26+。

所以如果准备完整使用 NestJS 12 的新 CLI，最省事的办法还是直接使用官方推荐的 Active LTS。

这里也没有必要因为 ESM 就急着把 Jest 一起换掉。

@nestjs/testing 本身并没有绑定具体测试框架，现有 CommonJS + Jest 项目依然可以继续运行。

真正需要检查的是项目里有没有自己写的 bundler、test runner 或启动脚本，并且这些工具是不是默认假设所有依赖都是 CommonJS。

换句话说，NestJS 12 把自己切到了 ESM，但没有要求你的整个工程必须同一天完成 ESM 改造。

这个迁移策略其实挺务实。

参数校验：终于不用在 class-validator 上吊死

如果说 ESM 主要是基建变化，那么业务代码层面最明显的变化，大概就是 Standard Schema。

写过 NestJS 的人基本都熟悉以前那套组合：

text

class-validator
+
class-transformer
+
ValidationPipe

一个 DTO 写下来，属性上往往挂满装饰器：

ts

export class CreateUserDto {
  @IsString()
  name: string;

  @IsEmail()
  email: string;
}

这种写法跟 NestJS 自己的面向对象风格很搭。

但最近几年，TypeScript 项目明显开始往另外一个方向走。

Zod、Valibot、ArkType 这一类 Schema First 的库越来越常见，特别是同时维护前端、后端和共享类型的项目。

以前如果想直接在 NestJS 里使用 Zod，通常要自己写 Pipe，或者引入额外的第三方适配层。

验证可以解决，Swagger、响应转换和类型推导又是另外一回事。

NestJS 12 开始把这件事情正式收进框架内部。

现在参数装饰器可以直接绑定符合 Standard Schema 规范的 schema：

ts

type CreateUserDto = z.infer<typeof createUserSchema>;

@Post()
create(
  @Body({ schema: createUserSchema })
  body: CreateUserDto,
) {
  return this.userService.create(body);
}

再配合框架内置的：

ts

app.useGlobalPipes(
  new StandardSchemaValidationPipe(),
);

请求参数就可以直接按照 Schema 验证。

这样连专门声明 DTO class 都不一定需要了，TypeScript 类型可以直接从 Schema 推导：

text

Schema
  ↓
运行时验证
  ↓
TypeScript 类型

更重要的是，NestJS 没有给 Zod 做一个专用绑定。

它真正支持的是 Standard Schema。

只要某个校验库实现这个社区规范，就可以接进来。

目前 Zod、Valibot、ArkType 等库都属于这条路线。

在响应端，NestJS 12 也提供了：

text

StandardSchemaSerializerInterceptor

用于对输出数据进行验证和转换。

这样同一套 Schema 开始有机会贯穿：

text

请求校验
   ↓
类型推导
   ↓
业务逻辑
   ↓
响应验证 / 转换
   ↓
OpenAPI

不过这里有一个边界需要说明。

Standard Schema 本身不等于 OpenAPI Schema。

如果某个库同时支持 Standard JSON Schema 扩展，NestJS Swagger 可以比较直接地把它转换成 OpenAPI 描述；如果没有，就需要额外提供 standardSchemaConverter。

所以更准确地说，NestJS 12 是把“同一套 Schema 贯穿整个类型链路”这条路打通了，而不是所有库都能无条件自动生成 Swagger。

原来的 class-validator 也没有被废弃。

ValidationPipe、ClassSerializerInterceptor 依然可以继续使用。

所以现在 NestJS 的验证体系更像是：

text

               ┌─ class-validator
               │
NestJS ─────────┤
               │
               └─ Standard Schema
                     ├─ Zod
                     ├─ Valibot
                     └─ ArkType

两种思路并存。

老项目不用动，新项目则多了一条更现代的选择。

CLI 工具链换血：Oxlint、Vitest 和 Rspack 开始上位

很多团队升级 NestJS 大版本时，往往只盯着框架 API。

但这次 Nest CLI 的变化其实非常能说明官方接下来想往哪里走。

首先，CLI 自己已经全面迁移到 ESM。

内部测试从 Jest 迁移到了 Vitest，同时官方还给各个命令补了更多端到端测试。

更重要的是，新项目的默认工具开始变化。

NestJS 12 里：

新生成的项目默认使用 Oxlint；
ESM 项目默认使用 Vitest；
CommonJS 项目继续默认使用 Jest；
Monorepo 默认 bundler 改成 Rspack；
webpack 相关 CLI 配置已经进入 deprecated 状态；
Bun 正式加入 CLI 支持的包管理器列表。

这里有个地方很容易理解错。

NestJS 并没有把所有项目统一改成：

text

Rspack + Oxlint + Vitest + Bun

而是针对不同场景重新选择默认值。

比如普通 CommonJS 项目仍然可以使用 Jest；Rspack 主要成为 Monorepo 的默认 bundler；Bun 只是和 npm、pnpm、yarn 一样，进入 CLI 支持列表，并没有变成默认包管理器。

真正统一发生变化的是 Oxlint。

无论 ESM 还是 CommonJS，新生成的项目都开始默认使用 Oxlint，而不是 ESLint。

这个变化其实挺有代表性。

过去一个典型 NestJS 工程，默认技术栈大概是：

text

CommonJS
Jest
ESLint
Webpack

现在则开始变成：

text

ESM / CommonJS
Vitest / Jest
Oxlint
Rspack（Monorepo）

不一定所有项目都要采用完全相同的一套组合。

但方向已经很明显：

NestJS 正在把默认脚手架往更现代、更快的一批 Node.js 工程工具迁移。

这也说明过去几年 Rust 工具链在 JavaScript 生态里的扩张，已经开始真正进入主流框架的默认配置。

新增 nest upgrade：机械迁移开始交给 CLI

以前升级 NestJS 大版本，最烦的往往不是 Breaking Change 本身。

而是大量重复的机械工作。

先修改：

text

@nestjs/core
@nestjs/common
@nestjs/platform-express
@nestjs/swagger
@nestjs/graphql
...

然后再翻迁移指南，一个一个看外围依赖有没有变。

NestJS 12 开始把这个流程正式交给 CLI。

升级 CLI：

bash

npm i -g @nestjs/cli@latest @nestjs/schematics@latest

然后进入项目执行：

bash

nest upgrade

CLI 会统一升级 NestJS 官方依赖，并自动执行一部分可以机械完成的迁移。

比如：

text

Webpack CLI 配置
        ↓
Rspack

GraphQL Playground
        ↓
GraphiQL

subscriptions-transport-ws
        ↓
graphql-ws

旧版 nats
        ↓
@nats-io/*

同时还会处理部分 @nestjs/config、Joi 和 Jest 相关依赖升级。

对于不能自动完成的 Breaking Changes，CLI 会扫描项目并给出迁移报告和提醒，让开发者继续人工处理。

真正执行之前，还可以先跑：

bash

nest upgrade --dry-run

提前看看它准备修改哪些文件和依赖。

这一点挺重要。

因为 NestJS 12 虽然明显在推动 ESM、Vitest 和 Oxlint，但 nest upgrade 并不会因为这些已经成为新项目默认值，就直接把老项目全部强制迁过去。

老项目依然可以继续：

text

CommonJS
+
Jest
+
原有工程配置

先只升级 NestJS 本身。

等系统稳定以后，再决定什么时候单独迁移测试框架、模块规范或者构建工具。

相比一次性把所有东西全掀掉，这种方式对生产项目明显友好得多。

官方下场做监控：@nestjs/observe

NestJS 12 另一个比较值得注意的动作，是官方推出了自己的可观测性 SDK：

text

@nestjs/observe

过去做 Node.js APM，大家一般会想到：

text

OpenTelemetry
Datadog
New Relic
Sentry
各种 APM Agent

这些方案通常从 Node.js 运行时、HTTP Server、数据库 Driver 这些层面做 instrumentation。

@nestjs/observe 的切入点有点不一样。

它直接接入 NestJS 自身的应用生命周期：

ts

const app = await NestFactory.create(AppModule, {
  instrument: ObserveInstrument,
});

因为 NestJS 本身知道：

text

哪个是 Controller
哪个是 Provider
哪个是 Guard
哪个是 Interceptor
哪个是 Pipe
哪个是 Resolver
哪个是 Queue Consumer

所以它天然能够观察到比普通 HTTP Agent 更接近业务代码的调用信息。

传统监控可能告诉你：

text

POST /orders
耗时 800ms

而 NestJS Observe 可以进一步把 Trace 拆到具体的 Controller、Provider 和方法层面，例如：

text

OrdersService.recalculate

到底花了多少时间。

这个体验上的差别其实挺大。

特别是 NestJS 项目普遍大量使用：

text

Dependency Injection
Guards
Interceptors
Providers
Queue
Cron
Microservices

只在 HTTP 层看一个请求耗时，经常并不知道真正慢在哪里。

NestJS 自己做 instrumentation，就有机会直接拿到这些框架语义。

目前自动 instrumentation 已经覆盖 HTTP、GraphQL、gRPC、Nest Microservices、Queue Consumer 和后台任务等常见场景。

同时还提供 Request、Trace、Error、运行时 profiling、自定义 metrics 等能力。

日志也可以和 Trace 建立关联。

不过完整日志转发需要额外开启 forwardLogs，并不是简单安装 SDK 后所有日志都会自动上传。

所以把它理解成：

text

NestJS-aware Observability

可能比单纯说“官方 APM”更准确。

另外，新版 CLI 还加入了：

bash

nest deploy

可以直接接入 Nest 官方的 Mau 部署服务。

把这两件事放在一起看，其实很有意思。

NestJS 正在逐渐从：

text

后端 Web Framework

往：

text

Node.js Application Platform

移动。

CLI、部署、升级、Observability，这些原本经常交给外围工具完成的能力，开始逐渐进入官方体系。

当然，这不代表已有的 Prometheus、Grafana、Tempo、Loki 或商业 APM 需要全部推倒重来。

成熟团队本来就可能已经有完整的监控规范。

但对于中小项目来说，一个能直接理解 Nest Controller、Provider、Queue 和 Cron 的官方 instrumentation 层，确实能省掉不少接入工作。

几个默默解决生产痛点的小细节

除了这些大方向变化，NestJS 12 还有几个小功能，看起来不起眼，但都是生产环境里比较容易踩的坑。

第一个是路由冲突检测。

例如：

ts

@Get(':id')
findOne() {}

@Get('me')
getCurrentUser() {}

在依赖声明顺序匹配路由的环境里，/me 有可能先撞进前面的 :id。

NestJS 12 可以配置：

ts

const app = await NestFactory.create(AppModule, {
  routeConflictPolicy: {
    duplicate: 'error',
    shadow: 'warn',
  },
  routeResolutionStrategy: 'specificity',
});

框架可以在启动阶段检查重复路由和路由遮蔽问题。

对于 Express 来说，这个功能尤其有价值。

因为 Express 的路由匹配很依赖注册顺序。

Fastify 底层使用的 find-my-way 本身就会按照路由 specificity 进行处理，所以 shadow 和 specificity 带来的变化没有 Express 那么明显，不过重复路由检测仍然有价值。

第二个小变化，是异常开始支持机器可读的 errorCode：

ts

throw new BadRequestException(
  'Password is too weak',
  {
    errorCode: 'WEAK_PASSWORD',
  },
);

以前前端经常需要：

ts

if (error.message === 'Password is too weak') {
  // ...
}

拿自然语言文案判断业务错误。

文案稍微一改，逻辑就跟着挂。

现在可以直接根据：

text

WEAK_PASSWORD

这种稳定错误码做判断。

这种变化不大，但非常实用。

第三个是 Logger 对结构化参数的支持更完整了：

ts

logger.log('User created', {
  userId: 1,
  email: 'foo@bar.com',
});

附加对象会作为结构化数据和日志绑定。

在 JSON 日志模式下，默认会放到 params 字段，也可以通过 flattenParams 展开。

对于需要把日志推到 ELK、Loki 或其他日志检索系统的项目来说，这比自己不断拼字符串靠谱得多。

这些功能单独看都不是“大版本级别”的明星特性。

但它们有一个共同点：

NestJS 开始越来越多地解决一个项目运行几年之后才会真正遇到的问题。

而不只是继续优化“如何快速写一个 Controller”。

面对这次升级，我的落地建议

如果是新项目，我会比较放心地直接采用 NestJS 12 的新路线：

text

Node.js Active LTS
+
ESM
+
Standard Schema / Zod
+
Vitest
+
Oxlint

如果是 Monorepo，还可以直接考虑官方默认的 Rspack。

这套工具链的特点很明确：

模块系统更新了，验证层开始 Schema First，lint 和测试工具也换成了更轻、更快的新一代方案。

但如果手里维护的是 NestJS 10 或 11 的生产项目，我反而不建议一次改太多东西。

比较稳妥的升级顺序是：

text

升级 Node.js
      ↓
nest upgrade --dry-run
      ↓
nest upgrade
      ↓
处理 Breaking Changes
      ↓
编译 + 测试
      ↓
上线

先让 NestJS 12 本身跑稳。

然后再单独考虑：

text

CommonJS → ESM

Jest → Vitest

ESLint → Oxlint

Webpack → Rspack

这些事情完全可以拆开做。

尤其不要因为 NestJS 自己已经 ESM 化，就觉得自己的业务项目也必须在同一个 PR 里全部变成 ESM。

NestJS 12 其实已经特意给老项目留出了过渡空间。

写在最后

NestJS 12 没有重新发明 NestJS。

Controller 还是 Controller。

Provider 还是 Provider。

Dependency Injection 还是原来那套 Dependency Injection。

业务开发者日常接触最多的东西，并没有突然发生巨变。

真正被重新整理的，是框架下面那一层。

CommonJS 开始退出核心包。

Standard Schema 正式进入验证体系。

Oxlint 进入默认脚手架。

Vitest 开始负责 ESM 项目的测试。

Rspack 成为 Monorepo 的默认 bundler。

CLI 开始负责自动迁移。

框架甚至自己下场做 Observability 和 Deploy。

所以我觉得 NestJS 12 最值得关注的，并不是某一个单独的新 API。

它更像是在回答一个问题：

到了 2026 年，一个现代 Node.js 后端项目的默认工具链，到底应该长什么样？

NestJS 12 给出的答案，已经和几年前明显不一样了。