Node 18 升级后，NestJS 项目中基于 src/ 的绝对路径导入（如 import { User } from 'src/modules/user/entities/user.entity'）因模块解析机制变化而报错，可通过 TypeScript 路径别名配合 baseUrl 和 paths 配置彻底解决，无需手动修改上千个文件。
node 18 升级后，nestjs 项目中基于 `src/` 的绝对路径导入（如 `import { user } from 'src/modules/user/entities/user.entity'`）因模块解析机制变化而报错，可通过 typescript 路径别名配合 `baseurl` 和 `paths` 配置彻底解决，无需手动修改上千个文件。
该问题本质并非 NestJS 框架缺陷，而是 Node.js 18 对 ESM/CommonJS 混合加载及 TypeScript 模块解析行为的 stricter 处理所致。虽然 baseUrl: "./" 已在 tsconfig.json 中声明，但 TypeScript 编译器默认不会自动将 src/ 开头的路径映射为相对于 baseUrl 的模块路径——它仅在启用 paths 映射时才生效。因此，原始配置缺少关键的路径重映射声明，导致 import ... from 'src/...' 被当作未解析的裸模块（bare import），最终在运行时因 CommonJS 模块绑定顺序问题（如循环依赖或装饰器初始化时机）引发 ReferenceError: file_service_1 is not defined 等错误。
✅ 正确解法：启用并配置 compilerOptions.paths
在现有 tsconfig.json 的 compilerOptions 中添加 paths 字段，将 'src/*' 显式映射到 ['./src/*']：
{
"compilerOptions": {
"baseUrl": "./",
"paths": {
"src/*": ["src/*"]
},
// 其他原有配置保持不变...
"module": "commonjs",
"target": "ES2021",
"outDir": "./dist",
"declaration": true,
"sourceMap": true",
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"allowSyntheticDefaultImports": true,
"strictNullChecks": true,
"incremental": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"jsx": "react"
},
"include": ["src/**/*.ts", "src/**/*.tsx"],
"exclude": ["node_modules/**", "dist/**"]
}
⚠️ 注意事项：
- 必须保留 baseUrl: "./"，否则 paths 不生效；
- paths 中的键（如 "src/*"）是 TypeScript 编译期使用的模块名匹配模式，值（["src/*"]）是相对于 baseUrl 的物理路径数组；
- 修改后需重启 TypeScript 编译器与开发服务器（如 nest start --watch），确保增量编译识别新路径规则；
- 若使用 VS Code，请重启 TS 语言服务（Ctrl+Shift+P → “TypeScript: Restart TS server”），避免 IDE 缓存旧解析逻辑；
- 所有 import ... from 'src/xxx' 将被正确解析为 ./src/xxx，且生成的 .js 文件中仍保留 require('src/...') —— 此时需确保运行时 Node.js 能正确解析该路径。为保险起见，建议同时在 package.json 中添加 "type": "commonjs"（默认即为 CommonJS，但显式声明更稳妥）。
? 进阶建议：统一路径风格提升可维护性
除修复问题外，推荐将路径别名进一步规范化，例如：
"paths": {
"@src/*": ["src/*"],
"@modules/*": ["src/modules/*"],
"@entities/*": ["src/common/entities/*"],
"@services/*": ["src/common/services/*"]
}
随后代码中即可使用 import { User } from '@modules/user/entities/user.entity';，语义更清晰，重构成本更低。
总结：Node 14 到 18 的迁移问题核心在于 TypeScript 模块解析策略收紧，而非 Nest 或 Node 的兼容性断裂。通过 paths 显式声明路径映射，既符合 TypeScript 官方规范，又能零成本修复全部 1200+ 文件的导入路径，是兼顾稳定性、可维护性与工程效率的最佳实践。
