TypeScript声明文件未正常编译引发运行报错的排查与解决

问题场景 #

自定义扩展了Express的User接口，让它继承Prisma生成的Users类型，IDE中代码无错误提示，但使用ts-node启动应用时，出现类型错误：error TS2339: Property 'id' does not exist on type 'User'.

相关文件与配置 #

自定义类型定义文件 src/config/passport/lib.d.ts #

import { Users } from '@prisma/client';

declare global {
    namespace Express {
        interface User extends Users {}
    }
}

Passport序列化代码 src/config/passport/passport.ts #

passport.serializeUser((user, done) => {
    done(null, user.id);
});

tsconfig.json配置 #

{
  "compilerOptions": {
    "target": "es2016",                                
    "lib": ["es6"],                                    
    "module": "commonjs",                              
    "rootDir": "src",                                  
    "resolveJsonModule": true,                         
    "allowJs": true,                                   
    "outDir": "build",                                 
    "esModuleInterop": true,                       
    "forceConsistentCasingInFileNames": true,           
    "strict": true,                                    
    "noImplicitAny": true,                             
    "skipLibCheck": true                          
  }
}

文件路径 #

• src/config/passport/passport.ts
• src/config/passport/lib.d.ts

解决方法 #

问题出在ts-node的启动参数上：

• 原启动脚本：ts-node ./src/index.ts
• 修改后启动脚本：ts-node --files ./src/index.ts

原因：ts-node默认仅处理入口文件及直接依赖的文件，不会自动加载所有类型定义文件。添加--files参数后，ts-node会加载tsconfig中配置的所有文件，包括自定义的.d.ts类型扩展文件，这样运行时就能识别到扩展后的Express.User类型，从而正确解析user.id的类型。

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