本地环境无法运行NestJS应用 常规排查无效求解决方案

高概率根因及修复 #

1. tsconfig路径配置非法 #

你当前tsconfig.json里的paths配置完全不符合语法规范：

"paths": {
  "<rootDir>/": ["."]
}

<rootDir>不是tsconfig paths支持的合法占位符，加上你已经设置baseUrl: "./src/"，这个错误配置会直接导致ts-node、Nest CLI解析模块路径失败，启动直接崩溃。

修复方式：直接删除这段错误的paths配置，如果需要配置路径别名，使用合法写法，比如配置@指向src目录的话写成"@/*": ["*"]即可。改完配置后务必删除根目录下自动生成的*.tsbuildinfo增量编译缓存文件，否则配置不会生效。

2. Elasticsearch依赖版本不兼容 #

你项目中@nestjs/elasticsearch使用的是^8.0.0大版本，但底层依赖@elastic/elasticsearch锁死在7.10版本，两个跨大版本的客户端存在大量不兼容的Breaking Change，启动时客户端注入阶段就会抛出方法不存在、类型不匹配的错误。

修复方式：二选一即可

• 保留7.10版本的es客户端，将@nestjs/elasticsearch降级到7.x对应适配版本
• 保留8.x版本的nestjs es封装，将@elastic/elasticsearch升级到8.x对应版本
  调整版本后删除lock文件重新安装依赖。

3. NPM依赖安装损坏 #

你当前使用的NPM 8.5.4存在已知的依赖提升bug，对Prisma、Bull这类带原生二进制的包兼容性很差，很容易出现缓存内包损坏、原生二进制和当前系统/Node版本不匹配的问题，哪怕删了node_modules重装，只要用了坏的缓存还是会出问题。

执行以下命令彻底清理重装：

# 强制清空NPM全量缓存
npm cache clean --force
# 删除旧依赖和lock文件
rm -rf node_modules package-lock.json
# 强制从源码编译原生依赖，避免二进制不匹配
npm i --build-from-source

次高概率排查点 #

• 全局Nest CLI版本冲突：如果你全局安装的@nestjs/cli是9.x以上版本，跑8.x版本的Nest项目会直接启动失败，不要直接用全局nest命令，改用项目本地的CLI执行：npx nest start。
• 环境变量缺失：你的prebuild脚本会先执行src/checkEnvs.ts做环境变量校验，拉取新代码后如果没把.env.example复制为.env、必填环境变量缺失，构建流程会直接中断。注意.env文件默认不会被Git提交，同事本地能跑不代表你拉下来的代码里带了对应配置。
• Prisma客户端未生成：项目使用了Prisma作为ORM，每次拉完新代码、装完依赖后必须先执行npm run prisma:generate生成对应版本的客户端代码，否则启动时会直接报Prisma客户端不存在的错误。
• 全局NODE_PATH污染：检查系统是否配置了NODE_PATH环境变量，该变量会让Node优先从全局目录加载模块，和项目内依赖版本冲突。执行echo $NODE_PATH（Windows系统执行echo %NODE_PATH%），如果有输出值先清空该变量再启动。

定位问题的通用方法 #

如果以上操作做完还是启动失败，不要用nest start或者watch模式启动，直接执行以下命令绕开Nest CLI的包装层，直接用ts-node跑入口文件：

ts-node -r tsconfig-paths/register src/main.ts

此时抛出的错误栈不会被CLI包装，会直接显示具体出错的文件、行号和错误原因，能直接定位根因。

内容的提问来源于stack exchange，提问作者Kyle