0Pricing
NestJS Enterprise Backend APIs · レッスン

Multer InterceptorによるMultipartアップロード

FileInterceptorとFilesInterceptorを接続し、サイズ制限付きで単一ファイルおよび複数ファイルのアップロードを受け付けます

「Multer InterceptorによるMultipartアップロード」はCoddyKit上の無料NestJS Enterprise Backend APIsレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはNestJS Enterprise Backend APIs学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 NestJS Enterprise Backend APIsコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Multer for Uploads

HTTP file uploads use the multipart/form-data content type, which splits the request body into parts: text fields and binary file payloads separated by a boundary marker.

NestJS does not parse this format on its own. Instead it ships first-class wrappers around Multer, the de-facto Express middleware for multipart parsing. You consume Multer through interceptors rather than wiring middleware manually.

  • FileInterceptor — one file from a single field
  • FilesInterceptor — many files from one field
  • FileFieldsInterceptor — files across several named fields

This lesson focuses on the first two and on enforcing size limits.

Installing the Types

The interceptors live in @nestjs/platform-express, which is already present in a standard Nest app. You only need the Multer type definitions to type your handler parameters correctly.

Install the dev dependency so Express.Multer.File is recognized by TypeScript:

npm install -D @types/multer

// Now Express.Multer.File is available globally in TypeScript.
// It describes the in-memory/disk file object Multer attaches
// to the request, e.g. originalname, mimetype, size, buffer, path.

Single File with FileInterceptor

Bind FileInterceptor('field') with @UseInterceptors, where the string is the name of the form-data field carrying the file. Then read the parsed file with the @UploadedFile() decorator.

The decorated parameter is a single Express.Multer.File. Notice the parameter name in the form does not need to match the handler argument — only the interceptor's field string matters.

import { Controller, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';

@Controller('avatars')
export class AvatarsController {
  @Post()
  @UseInterceptors(FileInterceptor('avatar'))
  upload(@UploadedFile() file: Express.Multer.File) {
    return {
      name: file.originalname,
      type: file.mimetype,
      size: file.size,
    };
  }
}

Memory vs Disk Storage

By default Multer uses memory storage: the whole file lands in file.buffer as a Buffer. That is convenient for forwarding to S3 or processing in-process, but large files can exhaust RAM.

For local persistence use disk storage, where Multer streams to a path and gives you file.path instead of a buffer. Pass options as the second argument of the interceptor.

import { diskStorage } from 'multer';
import { extname } from 'path';
import { randomUUID } from 'crypto';

export const imageStorage = diskStorage({
  destination: './uploads/images',
  filename: (_req, file, cb) => {
    const unique = randomUUID();
    cb(null, `${unique}${extname(file.originalname)}`);
  },
});

// Usage:
// @UseInterceptors(FileInterceptor('photo', { storage: imageStorage }))

Enforcing a Size Limit

Never trust client-declared sizes. Cap the bytes Multer will accept via the limits.fileSize option (in bytes). When a file exceeds it, Multer aborts and Nest surfaces a 413-style error before your handler runs.

Combine fileSize with files to also bound the count of files in a multi-upload.

import { FileInterceptor } from '@nestjs/platform-express';

const FIVE_MB = 5 * 1024 * 1024;

@Post('avatar')
@UseInterceptors(
  FileInterceptor('avatar', {
    limits: { fileSize: FIVE_MB },
  }),
)
upload(@UploadedFile() file: Express.Multer.File) {
  return { stored: file.originalname };
}

Computing Limits Safely

Express limits are expressed in raw bytes, which is easy to get wrong by an order of magnitude. A tiny pure helper keeps the math explicit and testable, and it runs anywhere with no framework.

Below, mb converts megabytes to bytes and we sanity-check a candidate upload size against a cap.

function mb(n: number): number {
  return n * 1024 * 1024;
}

function withinLimit(sizeBytes: number, capMb: number): boolean {
  return sizeBytes <= mb(capMb);
}

const FILE_CAP_MB = 5;
console.log('5MB in bytes:', mb(FILE_CAP_MB));
console.log(withinLimit(mb(4), FILE_CAP_MB));   // true
console.log(withinLimit(mb(6), FILE_CAP_MB));   // false
console.log(withinLimit(5_242_880, FILE_CAP_MB)); // true (exactly 5MB)

Multiple Files with FilesInterceptor

FilesInterceptor('field', maxCount, options) accepts several files sent under the same field name. Read them with @UploadedFiles(), which yields an array.

The maxCount argument is a hard ceiling on how many files Nest will collect; extras trigger an error. Pair it with limits.fileSize for per-file byte caps.

import { Controller, Post, UploadedFiles, UseInterceptors } from '@nestjs/common';
import { FilesInterceptor } from '@nestjs/platform-express';

@Controller('gallery')
export class GalleryController {
  @Post()
  @UseInterceptors(
    FilesInterceptor('photos', 10, {
      limits: { fileSize: 5 * 1024 * 1024 },
    }),
  )
  upload(@UploadedFiles() files: Express.Multer.File[]) {
    return files.map((f) => ({ name: f.originalname, size: f.size }));
  }
}

Filtering by MIME Type

Size limits do not stop the wrong file type. Use fileFilter to accept or reject each part as it streams. Call the callback with (null, true) to keep a file or with an error to reject it.

Rejecting with a BadRequestException produces a clean 400 instead of a generic failure.

import { BadRequestException } from '@nestjs/common';
import { Request } from 'express';

export function imageFileFilter(
  _req: Request,
  file: Express.Multer.File,
  cb: (error: Error | null, accept: boolean) => void,
) {
  const allowed = ['image/png', 'image/jpeg', 'image/webp'];
  if (!allowed.includes(file.mimetype)) {
    return cb(new BadRequestException('Only PNG, JPEG, or WebP allowed'), false);
  }
  cb(null, true);
}

Validating with ParseFilePipe

Nest's built-in ParseFilePipe validates the already-parsed file declaratively inside the handler. It composes validators like MaxFileSizeValidator and FileTypeValidator, returning a 422 when they fail.

This is complementary to Multer's limits: Multer guards the stream, the pipe guards your business rules and gives clearer error messages.

import {
  ParseFilePipe,
  MaxFileSizeValidator,
  FileTypeValidator,
  UploadedFile,
} from '@nestjs/common';

@Post('avatar')
@UseInterceptors(FileInterceptor('avatar'))
upload(
  @UploadedFile(
    new ParseFilePipe({
      validators: [
        new MaxFileSizeValidator({ maxSize: 5 * 1024 * 1024 }),
        new FileTypeValidator({ fileType: /(png|jpe?g|webp)$/ }),
      ],
    }),
  )
  file: Express.Multer.File,
) {
  return { ok: true, name: file.originalname };
}

Centralizing Config with a Factory

Repeating storage, limits, and filters on every route is error-prone. Extract a single MulterOptions object (or a factory) and reuse it. Enterprise apps often register defaults globally via MulterModule.register() and override per-route only when needed.

This keeps caps consistent and makes raising a limit a one-line change.

import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface';
import { diskStorage } from 'multer';
import { imageFileFilter } from './image-file.filter';

export const imageUploadOptions: MulterOptions = {
  storage: diskStorage({ destination: './uploads/images' }),
  limits: { fileSize: 5 * 1024 * 1024, files: 10 },
  fileFilter: imageFileFilter,
};

// @UseInterceptors(FilesInterceptor('photos', 10, imageUploadOptions))

Handling the Size-Limit Error

When limits.fileSize is exceeded, Multer throws an error whose code is 'LIMIT_FILE_SIZE'. By default Nest wraps it, but you can map it to a friendly payload with an exception filter so clients get a clear, consistent message.

Translating low-level Multer codes into HTTP responses is a hallmark of production-grade upload endpoints.

import { ExceptionFilter, Catch, ArgumentsHost, HttpStatus } from '@nestjs/common';
import { MulterError } from 'multer';
import { Response } from 'express';

@Catch(MulterError)
export class MulterExceptionFilter implements ExceptionFilter {
  catch(err: MulterError, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse<Response>();
    const status =
      err.code === 'LIMIT_FILE_SIZE'
        ? HttpStatus.PAYLOAD_TOO_LARGE
        : HttpStatus.BAD_REQUEST;
    res.status(status).json({ statusCode: status, message: err.message });
  }
}

Quick Check

Test your understanding of choosing the right interceptor and reading its result.

Recap

You can now wire multipart uploads end to end in NestJS:

  • FileInterceptor('field', options) + @UploadedFile() for one file.
  • FilesInterceptor('field', maxCount, options) + @UploadedFiles() for many files under one field.
  • limits.fileSize (bytes) caps stream size; limits.files caps count; fileFilter rejects bad MIME types early.
  • diskStorage vs memory storage decides whether you get file.path or file.buffer.
  • ParseFilePipe with MaxFileSizeValidator/FileTypeValidator validates declaratively, and a MulterError filter maps LIMIT_FILE_SIZE to a clean 413.

Centralize these options in one factory so limits stay consistent across every upload route.

よくある質問

「Multer InterceptorによるMultipartアップロード」レッスンは無料ですか？

はい。「Multer InterceptorによるMultipartアップロード」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、NestJS Enterprise Backend APIsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 NestJS Enterprise Backend APIsコースには全4レッスンが含まれています。

「Multer InterceptorによるMultipartアップロード」で何を学びますか？

FileInterceptorとFilesInterceptorを接続し、サイズ制限付きで単一ファイルおよび複数ファイルのアップロードを受け付けます ブラウザで直接実行するハンズオンコードでNestJS Enterprise Backend APIsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

NestJS Enterprise Backend APIsを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのNestJS Enterprise Backend APIsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。

「Multer InterceptorによるMultipartアップロード」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このNestJS Enterprise Backend APIsレッスンでコードを書いて実行できますか？

はい。すべてのNestJS Enterprise Backend APIsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. Multer InterceptorによるMultipartアップロード
  2. StreamableFileによる大容量レスポンスのストリーミング
  3. Presigned URLによるS3への直接アップロード
  4. Sharpによる画像処理パイプライン
← NestJS Enterprise Backend APIsに戻る