NODE_ENV=production时GitLab流水线测试找不到类型定义的问题

问题概况 #

• 项目devDependencies已包含@types/bcrypt、@types/hbs、@types/multer等类型定义包
• GitLab流水线测试阶段执行步骤：
  1. npm install --production=false
  2. npm i jest
  3. npm run test
• 仅当NODE_ENV=production时出现大量类型定义找不到错误，本地执行相同步骤正常，已尝试npm install --only=prod && npm install --only=dev、npm ci --include=dev等安装方式均无效

错误示例 #

• 找不到模块'bcrypt'的声明文件，'/builds/onix-systems/breakout-network-backend/node_modules/bcrypt/bcrypt.js'隐式具有'any'类型，提示执行npm i --save-dev @types/bcrypt或添加包含declare module 'bcrypt';的声明文件
• 命名空间'global.Express'不存在导出成员'Multer'
• 找不到模块'hbs'的声明文件，'/builds/onix-systems/breakout-network-backend/node_modules/hbs/lib/hbs.js'隐式具有'any'类型，提示执行npm i --save-dev @types/hbs或添加包含declare module 'hbs';的声明文件

原因分析 #

1. NODE_ENV=production会触发npm或TypeScript的生产模式行为，可能忽略devDependencies中的类型定义解析逻辑
2. 项目依赖分类错误：dependencies中包含jest、ts-jest、@types/jest等开发工具包，导致生产环境下类型解析逻辑混乱
3. TypeScript配置（tsconfig.json）可能未正确指定类型定义文件路径

解决方案建议 #

1. 强制测试阶段使用非生产环境变量 #

在流水线测试步骤前显式设置环境变量，避免生产模式的依赖解析限制：

export NODE_ENV=development
npm install --production=false
npm run test

或直接在测试命令前临时覆盖：

NODE_ENV=development npm run test

2. 修正package.json依赖分类 #

将开发相关工具包从dependencies移至devDependencies，避免生产环境干扰：

• 需要移动的包：@types/jest、jest、ts-jest、prisma（@prisma/client保留在dependencies）

调整后示例：

"devDependencies": {
  // ... 原有devDependencies内容
  "@types/jest": "29.5.0",
  "jest": "29.5.0",
  "ts-jest": "29.1.0",
  "prisma": "4.8.1"
}

3. 检查并修正tsconfig.json配置 #

确保TypeScript正确加载node_modules/@types下的类型定义：

{
  "compilerOptions": {
    "typeRoots": ["node_modules/@types"],
    "types": ["node", "jest", "multer"]
  },
  "include": ["src/**/*", "test/**/*"],
  "exclude": ["node_modules"]
}

4. 使用npm ci确保依赖完整安装 #

npm ci严格按照package-lock.json安装所有依赖（包括devDependencies），不受NODE_ENV影响，替换原有install步骤：

export NODE_ENV=development
npm ci
npm run test

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