如何升级到NestJS 11与Express 5nestjs-starter-rest-api迁移踩坑完整实录【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-apinestjs-starter-rest-api 是一个基于 NestJS 的单体后端启动套件NestJS Starter Kit提供开箱即用的 REST API认证、用户、文章管理 TypeORM Swagger。本文完整记录它从 NestJS 10 升级到NestJS 11并同步迈入Express 5的迁移踩坑实录哪些改动看似吓人实则无感哪些代码必须修改以及如何用一轮测试把风险清零。一、升级前检查为什么不能直接npm install了事NestJS 11 的门槛比版本号的跨度看起来更高升级前先确认两件事Node.js 必须 ≥ 20v11 已彻底放弃 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/common/core/platform-express^10^11nestjs/config^3^4nestjs/swagger^7^11.3.0nestjs/typeorm^10^11nestjs/cli/schematics/testingdev^10^11注意nestjs/swagger直接从 7 跳到 11且需配合swagger-ui-express固定到5.0.1以保证与 Express 5 兼容——这个组合是新手最容易忽略的隐性坑。⚠️三、Express 5 的两大破坏性变更查询解析器与通配符路由1. Query 参数解析器从qs变为simpleExpress 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 buildTypeScript 立刻揪出了两处真正的破坏性变更坑 1JWT 策略编译报错——get改getOrThrowsrc/auth/strategies/jwt-auth.strategy.ts与src/auth/strategies/jwt-refresh.strategy.ts中passport-jwt的secretOrKey只接受string | Buffer而ConfigService.getstring()的返回类型是string | undefined类型检查直接失败。修复方式是把调用换成getOrThrowstring(jwt.publicKey)。这其实是一次语义升级密钥缺失时应用会在启动阶段就大声报错而不是悄悄注册一个坏掉的鉴权策略——对生产环境是好事。✅坑 2Swagger 装饰器类型收窄nestjs/swaggerv11 收紧了ApiProperty({ type })接受的联合类型。src/shared/dtos/base-api-response.dto.ts中自定义的ApiPropertyType联合过于宽泛混入了string、undefined等导致 TS 要么直接拒绝、要么匹配到错误的枚举重载。修复方式是把联合收窄为实际调用方真正用到的两种形式type ApiPropertyType | Typeunknown | [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 | undefinedsrc/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零破坏性安全修复 9 个只动了package-lock.json✅第二步待办bcrypt5 → 6运行时依赖独立 PR 鉴权链路回归可清除 6 个运行时高危项遗留compodoc链路仅开发依赖影响低观察即可关键经验先跑安全的npm audit fix把破坏性修复如 bcrypt 大版本拆成独立 PR 单独回归不要混进迁移 PR。八、迁移经验总结清单#行动项结论1升级全部nestjs/*到 v11✅ 必做ncu一键完成2types/express升 v5 swagger-ui-express锁 5.0.1✅ 必做易漏3Express 5 查询解析器检查✅ 扁平参数项目可免改4通配符路由*→*splat✅ 无此类路由则免改5Config v4 优先级变更影响面审查✅ 命名空间隔离则无感6getOrThrow替换 Swagger 类型收窄✅ 本项目两处真实改动7单测 e2e 全量回归✅ 98 30 全绿8npm audit分级修复✅ 安全项清零破坏性项独立跟进一句话总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何升级到NestJS 11与Express 5：nestjs-starter-rest-api迁移踩坑完整实录
如何升级到NestJS 11与Express 5nestjs-starter-rest-api迁移踩坑完整实录【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-apinestjs-starter-rest-api 是一个基于 NestJS 的单体后端启动套件NestJS Starter Kit提供开箱即用的 REST API认证、用户、文章管理 TypeORM Swagger。本文完整记录它从 NestJS 10 升级到NestJS 11并同步迈入Express 5的迁移踩坑实录哪些改动看似吓人实则无感哪些代码必须修改以及如何用一轮测试把风险清零。一、升级前检查为什么不能直接npm install了事NestJS 11 的门槛比版本号的跨度看起来更高升级前先确认两件事Node.js 必须 ≥ 20v11 已彻底放弃 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/common/core/platform-express^10^11nestjs/config^3^4nestjs/swagger^7^11.3.0nestjs/typeorm^10^11nestjs/cli/schematics/testingdev^10^11注意nestjs/swagger直接从 7 跳到 11且需配合swagger-ui-express固定到5.0.1以保证与 Express 5 兼容——这个组合是新手最容易忽略的隐性坑。⚠️三、Express 5 的两大破坏性变更查询解析器与通配符路由1. Query 参数解析器从qs变为simpleExpress 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 buildTypeScript 立刻揪出了两处真正的破坏性变更坑 1JWT 策略编译报错——get改getOrThrowsrc/auth/strategies/jwt-auth.strategy.ts与src/auth/strategies/jwt-refresh.strategy.ts中passport-jwt的secretOrKey只接受string | Buffer而ConfigService.getstring()的返回类型是string | undefined类型检查直接失败。修复方式是把调用换成getOrThrowstring(jwt.publicKey)。这其实是一次语义升级密钥缺失时应用会在启动阶段就大声报错而不是悄悄注册一个坏掉的鉴权策略——对生产环境是好事。✅坑 2Swagger 装饰器类型收窄nestjs/swaggerv11 收紧了ApiProperty({ type })接受的联合类型。src/shared/dtos/base-api-response.dto.ts中自定义的ApiPropertyType联合过于宽泛混入了string、undefined等导致 TS 要么直接拒绝、要么匹配到错误的枚举重载。修复方式是把联合收窄为实际调用方真正用到的两种形式type ApiPropertyType | Typeunknown | [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 | undefinedsrc/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零破坏性安全修复 9 个只动了package-lock.json✅第二步待办bcrypt5 → 6运行时依赖独立 PR 鉴权链路回归可清除 6 个运行时高危项遗留compodoc链路仅开发依赖影响低观察即可关键经验先跑安全的npm audit fix把破坏性修复如 bcrypt 大版本拆成独立 PR 单独回归不要混进迁移 PR。八、迁移经验总结清单#行动项结论1升级全部nestjs/*到 v11✅ 必做ncu一键完成2types/express升 v5 swagger-ui-express锁 5.0.1✅ 必做易漏3Express 5 查询解析器检查✅ 扁平参数项目可免改4通配符路由*→*splat✅ 无此类路由则免改5Config v4 优先级变更影响面审查✅ 命名空间隔离则无感6getOrThrow替换 Swagger 类型收窄✅ 本项目两处真实改动7单测 e2e 全量回归✅ 98 30 全绿8npm audit分级修复✅ 安全项清零破坏性项独立跟进一句话总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考