TS2717错误排查：本地正常Docker构建时UserModel类型冲突问题

本地开发环境执行TypeScript构建正常，但使用Docker+Node镜像构建时出现如下错误：

src/middlewares/auth.ts(16,13): error TS2717: Subsequent property declarations must have the same type.
Property 'user' must be of type 'UserModel', but here has type 'UserModel'.

相关代码配置如下：

auth.ts #

import { Request, Response, NextFunction } from 'express';
import { AuthService } from '../services/auth.service';
import { UserService } from '../services/user.service';
import { UserModel } from '../models/user.model';
import { Resp } from '../utils/Response';
import { AuthErrEnum } from '../enums/auth/auth-message.enum';

const authService = new AuthService();
const userService = new UserService();

declare global {
    namespace Express {
        interface Request {
            user: UserModel;
        }
    }
}

export async function authMiddleware(req: Request, res: Response, next: NextFunction) {

    const authorization = req.headers.authorization;
    if(!authorization) return Resp.error(AuthErrEnum.NO_TOKEN_PROVIDED,401).send(res)

    const token = authorization.split(' ')[1];
    if(!token) {
        return Resp.error(AuthErrEnum.NO_TOKEN_PROVIDED, 401).send(res)
    }

    let payload;
    try{
        payload = await authService.decodeToken(token);
    } catch(err) {
        return Resp.error(AuthErrEnum.INVALID_TOKEN, 401).send(res)  
    }    
    
    const user = await userService.findWithRelations(payload.id);
     
    req.user = user;

    next();
}

package.json #

{
  "scripts": {
    "dev": "ts-node-dev src/app.ts",
    "start": "node build/app.js",
    "build": "del build/* && tsc",
  },
  "dependencies": {
    "ts-node-dev": "^2.0.0",
    "typescript": "^4.2.4",
  },
  "devDependencies": {
    "@types/express": "^4.17.13",
    "@types/node": "^16.10.3",
    "del-cli": "^4.0.1"
  }
}

tsconfig.json #

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "allowJs": true,
    "outDir": "./build/",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "exclude": [
    "nginx",
    "ecosystem.config.js"
  ]
}

原因与解决方案 #

这个错误的核心是TypeScript将同一个UserModel识别为两个不同的类型，导致全局声明的Express Request.user属性出现重复声明冲突，常见原因和解决办法如下：

1. 文件路径大小写不一致 #

Docker基于Linux环境，对文件路径大小写严格敏感；而本地Windows/macOS通常忽略大小写。如果代码中导入UserModel的路径（比如../models/user.model）和实际文件的大小写（比如User.model.ts）不匹配，会导致TypeScript在Docker中解析出两个不同的模块，进而认为是不同的类型。

• 解决：统一代码中所有导入路径的大小写，确保和实际文件完全一致。

2. 全局类型重复声明 #

如果项目中多个文件都对Express的Request接口进行了扩展声明（比如其他中间件也写了declare global { namespace Express { interface Request { user: UserModel } } }），会导致重复声明冲突。

• 解决：将Express类型扩展统一放到单独的类型声明文件中（比如src/types/express.d.ts），确保只声明一次。

3. Docker构建缓存问题 #

Docker的构建缓存可能保留了旧的依赖或构建产物，导致类型解析异常。

• 解决：执行docker build --no-cache命令，强制清理缓存后重新构建。

4. TypeScript模块解析配置 #

虽然当前tsconfig使用commonjs模块，但可以明确指定moduleResolution为node，避免模块解析异常：

{
  "compilerOptions": {
    // ...其他配置
    "moduleResolution": "node"
  }
}

5. 检查UserModel导出 #

确保user.model.ts中UserModel的导出唯一，没有重复导出或命名冲突的情况。

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