调试Nest.js项目和源码

Nest.js 是当下最流行的 Node.js 服务端框架，它建立在 Express 之上，实现了 IOC 的架构模式，并且对很多方案都有集成，比如 websocket、graphql 等。

需要注意的是，本节不是讲 Nest.js 的原理，而是讲如何调试 Nest.js 的项目，如何调试 Nest.js 的源码。

调试 Nest.js 项目

方式一：使用 JavaScript Debug Terminal（推荐）

2024-2026 更新：最推荐的方式是使用 JavaScript Debug Terminal：

1. 在 VSCode 的 Terminal 面板中，点击 + 旁边的下拉箭头，选择 JavaScript Debug Terminal
2. 在该终端中执行 npm run start:dev
3. Nest.js 项目会自动进入调试模式

在 controller 里打个断点，浏览器访问 http://localhost:3000，代码就会在断点处断住。

方式二：使用 launch.json 配置

创建一个 Node 调试配置：

{
  "type": "node",
  "request": "launch",
  "name": "Nest.js Debug",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "start:dev"],
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal"
}

这里 console 要设置为 integratedTerminal，这样日志会输出在 terminal，与手动执行 npm run start:dev 的行为一致。

在 controller 打个断点，浏览器访问 http://localhost:3000，代码就会在断点处断住。

注意：用 debug 方式运行之前要把之前启动的服务关掉，不然端口会被占用。

调试 Nest.js 源码

调用栈里，我们的代码之前的部分，就是 Nest.js 框架的代码。但这是编译后的代码，而我们是想调试 Nest 的 TypeScript 源码的，这就需要用到 sourcemap 了。

从 npm registry 下载的包是没有 sourcemap 的代码，想要 sourcemap，需要自己 build 源码。

步骤一：下载并构建 Nest.js 源码

git clone --depth=1 --single-branch https://github.com/nestjs/nest
cd nest
npm install
npm run build

2024-2026 更新：Nest.js 的构建系统已从纯 tsc 迁移到 tsc + tsc-alias（处理路径别名）。构建后的产物会自动放到 node_modules/@nestjs 目录下。

步骤二：生成 sourcemap

修改 packages/tsconfig.build.json，设置 sourceMap: true 和 inlineSources: true：

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "sourceRoot": "/absolute/path/to/nest/packages/"
  }
}

sourceRoot 设置为 Nest.js 源码的绝对路径，这样 sourcemap 到的路径就是绝对路径，可以在 VSCode 中直接打开对应的源码文件。

再次执行 npm run build，就会生成带有 sourcemap 的代码。

步骤三：配置调试

创建调试配置，并去掉 resolveSourceMapLocations 中对 node_modules 的排除：

{
  "type": "node",
  "request": "launch",
  "name": "Nest Source Debug",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "start"],
  "cwd": "${workspaceFolder}/sample/01-cats-app/",
  "console": "integratedTerminal",
  "skipFiles": ["<node_internals>/**"],
  "resolveSourceMapLocations": [
    "${workspaceFolder}/**",
    "**/node_modules/@nestjs/**"
  ]
}

关键点：默认情况下，resolveSourceMapLocations 会排除 node_modules 目录。要调试 Nest.js 源码，必须明确包含 @nestjs 的路径。

在 controller 里打个断点，浏览器访问，代码就会在断点处断住，并且调用栈中显示的就是 Nest 的 TypeScript 源码。

Nest.js 核心执行流程

2025-2026 更新：NestJS 11 默认底层 HTTP 平台升级为 Express 5（Fastify 5 作为替代平台同步升级）。Express 5 的变化会影响调试时的观察点：query parser 默认改为扩展模式（?a=1&a=2 会解析为数组）、废弃的 app.del() 等 API 被移除、通配符路由语法从 * 改为 *splat。调试时可在 ExpressAdapter 中打断点观察平台差异。

关键断点位置推荐：