Typescript搭配multer上传到S3后无法访问req.file扩展属性问题

你遇到的是TypeScript类型不匹配问题，和业务逻辑实现无关：

• multer 定义的默认 Express.Multer.File 类型仅包含 fieldname、originalname、encoding、mimetype、size 这几个基础属性
• multer-s3 扩展的 bucket、key、location、etag 等S3专属属性没有被包含在默认类型定义中，所以TypeScript识别不到，触发编译报错和编辑器标红。

前置准备 #

首先确认已安装对应的类型定义包，没有的话执行安装：

npm install @types/multer @types/multer-s3 -D
# 或使用yarn
yarn add @types/multer @types/multer-s3 -D

方案1：临时类型断言（快速解决单文件使用场景） #

直接在控制器中对req.file做类型断言，指定为multer-s3的文件类型即可：

import { Request, Response } from "express";

export class CreateAttachmentController {
  async handle ( req: Request, res: Response ){
    try {
      // 核心：将req.file断言为multer-s3的文件类型
      const requestedFile = req.file as Express.MulterS3.File;
      // 此时可以正常解构所有S3专属属性，编辑器也会有智能提示
      const { originalname, mimetype, size, key, location } = requestedFile;

      const attachmentRepository = getCustomRepository(AttachmentRepository);
      const attachment = await attachmentRepository.create({
        original_name: originalname,
        mime_type: mimetype,
        size,
        s3_key: key,
        access_url: location
      });

      await attachmentRepository.save(attachment);
      return res.json(attachment);
    } catch (err) {
      return res.status(500).json({ message: '文件上传失败' });
    }
  }
};

方案2：全局扩展Request类型（适合多接口使用S3上传的场景） #

如果项目中有多个接口用到S3上传，可以直接扩展Express的Request类型，后续所有接口不用再单独做类型断言：

1. 新建类型声明文件 src/typings/express.d.ts，写入以下内容：

declare global {
  namespace Express {
    interface Request {
      // 覆盖默认的file类型为multer-s3的文件类型
      file: MulterS3.File;
      // 如果有多文件上传需求，可额外添加files定义
      // files: MulterS3.File[];
    }
  }
}
export {};

2. 检查tsconfig.json的include配置，确保包含了声明文件路径：

{
  "include": ["src/**/*", "src/typings/**/*"]
}

配置完成后重启TS服务，所有接口的req.file都会自动识别为S3文件类型，直接访问对应属性即可。

兼容多存储类型的注意事项 #

如果你的项目同时支持本地存储和S3存储切换，建议增加类型守卫判断，避免本地存储场景下S3属性不存在的问题：

const isS3File = (file: Express.Multer.File | Express.MulterS3.File): file is Express.MulterS3.File => {
  return 'location' in file && 'key' in file;
}

// 使用时先判断
if (isS3File(req.file)) {
  // 此处可安全访问S3专属属性
} else {
  // 本地存储逻辑
}

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