如何升级到NestJS 11与Express 5：nestjs-starter-rest-api迁移踩坑完整实录

如何升级到NestJS 11与Express 5：nestjs-starter-rest-api迁移踩坑完整实录

【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api

nestjs-starter-rest-api 是一个基于 NestJS 的单体后端启动套件（NestJS Starter Kit，提供开箱即用的 REST API：认证、用户、文章管理 + TypeORM + Swagger）。本文完整记录它从 NestJS 10 升级到NestJS 11并同步迈入Express 5的迁移踩坑实录：哪些改动"看似吓人实则无感"，哪些代码必须修改，以及如何用一轮测试把风险清零。🚀

一、升级前检查：为什么不能直接npm install了事

NestJS 11 的门槛比版本号的跨度看起来更高，升级前先确认两件事：

• Node.js 必须 ≥ 20：v11 已彻底放弃 Node 16/18 支持。本项目的 Docker 环境已使用 Node 20.19.6，无需额外动作；
• Express 类型定义要跟上：@nestjs/platform-expressv11 默认集成 Express 5，因此@types/express需从^4升到^5（见 package.json）。

💡 建议升级前通读官方迁移要点，本项目将其整理在docs/nestjs-v11-migration/official-migration-guide.md，并用docs/nestjs-v11-migration/action-items.md做逐项核对清单——这是整个迁移"不乱"的关键。

二、一键升级所有 NestJS 11 包：npm-check-updates 快速操作

手动改十几个包版本号极易漏改，官方推荐用npm-check-updates按前缀批量升级：

npx npm-check-updates -u "/@nestjs.*/"

本项目实际完成的版本跳跃（详见package.json）：

注意@nestjs/swagger直接从 7 跳到 11，且需配合swagger-ui-express固定到5.0.1以保证与 Express 5 兼容——这个组合是新手最容易忽略的隐性坑。⚠️

三、Express 5 的两大破坏性变更：查询解析器与通配符路由

1. Query 参数解析器：从qs变为simple

Express 5 不再默认用qs解析查询参数，嵌套写法如?filter[where][name]=John将失效。排查方法很简单：

• 全局搜索@Query()与req.query的使用点；
• 本项目只有文章/用户列表两个分页端点，全部绑定到扁平字段（limit、offset）的PaginationParamsDto，扁平参数在新旧解析器下行为完全一致；
• 结论：无需修改src/main.ts，也不必把应用类型标注为NestExpressApplication。

若你的项目确实依赖嵌套查询，只需在src/main.ts中加一行：

app.set('query parser', 'extended');

2. 通配符路由语法：*必须命名

Express 5 要求通配符写成*splat而非裸*，中间件forRoutes('*')也要改为forRoutes('{*splat}')。本项目搜索结果为零——没有任何通配符路由，当前无改动，但以后新增此类路由时要记住这个新语法。

四、真正踩到的坑：两处必改代码

升级后执行npm run build，TypeScript 立刻揪出了两处真正的破坏性变更：

坑 1：JWT 策略编译报错——get改getOrThrow

src/auth/strategies/jwt-auth.strategy.ts与src/auth/strategies/jwt-refresh.strategy.ts中，passport-jwt的secretOrKey只接受string | Buffer，而ConfigService.get<string>()的返回类型是string | undefined，类型检查直接失败。

修复方式是把调用换成getOrThrow<string>('jwt.publicKey')。这其实是一次语义升级：密钥缺失时应用会在启动阶段就大声报错，而不是悄悄注册一个坏掉的鉴权策略——对生产环境是好事。✅

坑 2：Swagger 装饰器类型收窄

@nestjs/swaggerv11 收紧了ApiProperty({ type })接受的联合类型。src/shared/dtos/base-api-response.dto.ts中自定义的ApiPropertyType联合过于宽泛（混入了string、undefined等），导致 TS 要么直接拒绝、要么匹配到错误的枚举重载。

修复方式是把联合收窄为实际调用方真正用到的两种形式：

type ApiPropertyType = | Type<unknown> | [new (...args: any[]) => any];

全部 11 个调用点（SwaggerBaseApiResponse(SomeClass)及数组形式）无一需要改动，删掉的分支本就是死代码。

五、看似吓人实则无感：配置优先级与 Reflector 变更

以下两项官方 Breaking Change 经逐一核查后均无需改代码，但非常值得你的项目对照排查：

• @nestjs/configv4 优先级反转：ConfigService#get的读取顺序从"环境变量优先"变为"内部配置优先"。本项目在src/shared/configs/configuration.ts中使用小写字段（port、database.*、jwt.*），而环境变量是大写下划线（APP_PORT、DB_HOST，校验规则见src/shared/configs/module-options.ts），两套命名空间互不碰撞，三层优先级永远不会命中同一个 key，因此无影响；
• Reflector.getAllAndOverride返回类型变为T | undefined：src/auth/guards/roles.guard.ts中早已写了if (!requiredRoles) return true的空值守卫，属于"提前受益"；
• 动态模块解析算法变更：由深哈希去重改为对象引用比较，主要影响测试模块中的依赖实例定位。本项目测试全部通过；若你的 e2e 挂了，可用Test.createTestingModule({...}, { moduleIdGeneratorAlgorithm: 'deep-hash' })回退旧算法。

另外两项变更（生命周期销毁钩子倒序执行、全局模块中间件优先执行）经排查与本项目无关：无依赖特定关闭顺序，中间件也全部通过main.ts的app.use()全局挂载。

六、升级后验证：98 个单测 + 30 个 e2e 全绿

迁移是否完成，不看版本号看测试。执行三件套：

npm run build # 类型检查 + 编译 npm run test # 98 个单元测试 npm run test:e2e # 30 个端到端测试

三条全绿才算真正落地。test/目录下的article、auth、user三组 e2e 用例覆盖了注册、登录、JWT 刷新、文章读写等核心链路，恰好也覆盖了本次改动的两个重灾区（JWT 策略与 Swagger 响应装饰器）。

七、顺手清坑：npm audit 漏洞从 17 降到 8

迁移完成后跑npm audit，初始报出 17 个漏洞（含 1 个 Critical）。分级处理后的路径（完整分析见docs/nestjs-v11-migration/npm-audit-summary.md）：

关键经验：先跑安全的npm audit fix，把破坏性修复（如 bcrypt 大版本）拆成独立 PR 单独回归，不要混进迁移 PR。

八、迁移经验总结清单

一句话总结：NestJS 11 + Express 5 的迁移，八成是"核对清单"，两成是"类型系统逼你改对"。带着清单逐条过、用测试收口，这个版本跨度远比想象中平滑。🎯

📚 迁移过程沉淀的三份文档（升级清单、官方指南摘要、审计总结）位于docs/nestjs-v11-migration/目录，可作为你项目的迁移模板参考；如需对照完整代码，可克隆仓库：git clone https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api。

【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api