Node仅在部分环境报‘Cannot find type definition’错误的原因排查

接手一个基于Strapi CMS的TypeScript项目，该项目在开发者的MacBook上运行正常，但在我的Windows、WSL2 Ubuntu 22.04、谷歌云Ubuntu 22.04，以及朋友同版本Node/npm/yarn的MacBook上均触发如下TypeScript错误：

error TS2688: Cannot find type definition file for 'express-unless'.
  The file is in the program because:
    Entry point for implicit type library 'express-unless'

但项目在Docker容器中可正常构建运行，Dockerfile内容如下：

FROM node:18.19.1-slim
ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}
WORKDIR /opt/
COPY package.json yarn.lock ./
RUN yarn global add node-gyp
RUN yarn config set network-timeout 600000 -g && yarn install
ENV PATH /opt/node_modules/.bin:$PATH
WORKDIR /opt/app
COPY . .
RUN chown -R node:node /opt/app
USER node
RUN ["yarn", "build"]
EXPOSE 1337
CMD ["yarn", "start"]

我的环境版本：

node -v
v18.19.1
npm -v 
10.2.4
yarn -v
1.22.22

最终发现删除.\node_modules\@types\express-unless目录即可解决问题，现咨询两个核心问题：

1. 该错误的成因是什么？
2. 为何开发者电脑及Docker容器中从未出现此错误？

1. 错误成因 #

@types/express-unless这个类型定义包本身存在结构缺陷：它的package.json中没有正确配置types字段（或者配置的路径无效），导致TypeScript无法识别到它的类型入口文件。

TypeScript会自动扫描node_modules/@types目录下的所有包，将其作为隐式类型库加载。当它尝试加载express-unless的类型定义时，找不到合法的入口文件，就会抛出TS2688错误。而删除该目录后，TypeScript不再尝试加载这个有问题的包，且项目实际运行中并不依赖它的类型定义（要么是依赖的express-unless包本身自带了类型，要么是项目中并未直接使用该包的类型），因此错误消失。

2. 为何开发者电脑及Docker容器无报错 #

开发者电脑 #

• 可能开发者本地的@types/express-unless是旧版本/修复过的版本：该包的某个旧版本是正常的，开发者本地安装的是该版本，而项目的yarn.lock文件未锁定这个包的版本，导致其他人安装时拉取了有缺陷的新版本。
• 开发者本地的TS配置有特殊规则：比如tsconfig.json中通过exclude字段排除了@types/express-unless目录，或者调整了typeRoots配置，让TS不扫描这个包。
• 开发者曾手动修复过该目录：比如补全了package.json的types字段，但未将修改提交到项目仓库中。

Docker容器 #

Docker构建时设置了NODE_ENV=production，Yarn在生产环境下默认不会安装devDependencies。而@types/express-unless属于开发依赖（类型定义包通常都是dev依赖），因此Docker容器中根本没有安装这个包，自然不会触发TS加载它的逻辑，也就不会报错。

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