Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Upload de fichiers avec Multer (FileInterceptor, validation de fichiers)

Cette leçon apprend à recevoir des fichiers dans une API NestJS avec Multer, intégré à @nestjs/platform-express. Elle présente FileInterceptor et @UploadedFile, les informations reçues sur le fichier,...

0 chapitres 0 QCM Accès gratuit
Upload de fichiers avec Multer (FileInterceptor, validation de fichiers)

À propos de ce cours

Cette leçon apprend à recevoir des fichiers dans une API NestJS avec Multer, intégré à @nestjs/platform-express. Elle présente FileInterceptor et @UploadedFile, les informations reçues sur le fichier, puis la validation avec ParseFilePipe : taille maximale et type détecté d'après le contenu du fichier, pas d'après ce qu'annonce le client. L'exécution compare l'enregistrement en mémoire puis sur disque sous un nom aléatoire, et la variante diskStorage, qui laisse passer un texte déguisé en image. Elle traite aussi le fichier facultatif, la limite de Multer, et l'envoi de plusieurs fichiers. Activités corrigées.

Objectifs de la leçon

  • Recevoir un ou plusieurs fichiers avec FileInterceptor et @UploadedFile.
  • Valider la taille et le type réel d'un fichier avec ParseFilePipe.
  • Enregistrer un fichier de façon sûre, sous un nom généré.
  • Connaître les limites de diskStorage.

Versions: ce chapitre a été exécuté avec NestJS 12.5 dans un projet créé par nest new en choisissant CommonJS (TypeScript 6). Deux réglages de ce projet comptent ici :

  • "isolatedModules": true: une interface utilisée dans la signature d'une méthode décorée s'importe avec import type (exemple : import type { Cache } from 'cache-manager'), sinon erreur TS1272 ;
  • "types": ["node", "jest"]: le type Express.Multer.File n'est pas chargé automatiquement. Ajoutez "multer" à cette liste dans tsconfig.json (sinon : « Namespace 'global.Express' has no exported member 'Multer' »).

Sur un projet NestJS 11, les paquets de ce chapitre s'installent de la même façon, sauf @nestjs/serve-static: utilisez @nestjs/serve-static@5 (la version 12 exige NestJS 12).

Comment un fichier arrive-t-il à l'API ?

Un fichier ne s'envoie pas en JSON : le client utilise le format multipart/form-data, celui d'un formulaire HTML avec <input type="file">. Le corps de la requête contient plusieurs parties: des champs texte (legende) et des fichiers (fichier), chacun avec son nom d'origine et son type déclaré.

NestJS (avec Express) s'appuie sur Multer, déjà inclus dans @nestjs/platform-express. Il suffit d'installer les types :

npm install -D @types/multer
# puis, dans tsconfig.json : "types": ["node", "jest", "multer"]

Parcours d'un fichier envoyé à l'API

Multer lit le fichier, ParseFilePipe le valide, le service l'enregistre sous un nom généré.

Le contrôleur

📄 src/photos/photos.controller.ts

import {
  Body, Controller, FileTypeValidator, HttpStatus, MaxFileSizeValidator, ParseFilePipe, ParseFilePipeBuilder,
  Post, UploadedFile, UploadedFiles, UseInterceptors,
} from '@nestjs/common';
import { FileFieldsInterceptor, FileInterceptor, FilesInterceptor } from '@nestjs/platform-express';
import { IsString, Length } from 'class-validator';
import { diskStorage } from 'multer';
import { randomUUID } from 'node:crypto';
import { writeFile } from 'node:fs/promises';
import { extname, join } from 'node:path';

export class LegendeDto {
  @IsString()
  @Length(2, 80)
  legende: string;
}

// Validation commune : 2 Mo au maximum, PNG ou JPEG reconnu d'après le CONTENU du fichier
const validationImage = () =>
  new ParseFilePipe({
    validators: [
      new MaxFileSizeValidator({ maxSize: 2 * 1024 * 1024, errorMessage: 'Fichier trop volumineux (2 Mo maximum)' }),
      new FileTypeValidator({ fileType: /^image\/(png|jpeg)$/, overrideMimeType: true }),
    ],
  });

@Controller('photos')
export class PhotosController {
  // 1. Le minimum : le fichier est gardé en mémoire (file.buffer)
  @Post('memoire')
  @UseInterceptors(FileInterceptor('fichier'))
  memoire(@UploadedFile() fichier: Express.Multer.File) {
    const { fieldname, originalname, mimetype, size } = fichier;
    return { fieldname, originalname, mimetype, size, buffer: `Buffer de ${fichier.buffer.length} octets` };
  }

  // 2. Méthode recommandée : validation en mémoire, PUIS enregistrement sous un nom aléatoire
  @Post()
  @UseInterceptors(FileInterceptor('fichier'))
  async deposer(@UploadedFile(validationImage()) fichier: Express.Multer.File, @Body() dto: LegendeDto) {
    const extension = fichier.mimetype === 'image/png' ? '.png' : '.jpg';      // déduite du type détecté
    const nomStocke = randomUUID() + extension;
    await writeFile(join('uploads', nomStocke), fichier.buffer);
    return { legende: dto.legende, nomOriginal: fichier.originalname, nomStocke, taille: fichier.size, type: fichier.mimetype };
  }

  // 3. Variante diskStorage : Multer écrit le fichier AVANT la validation
  @Post('disque')
  @UseInterceptors(
    FileInterceptor('fichier', {
      storage: diskStorage({
        destination: './uploads-disque',
        filename: (_req, f, rappel) => rappel(null, randomUUID() + extname(f.originalname).toLowerCase()),
      }),
    }),
  )
  disque(
    @UploadedFile(
      new ParseFilePipe({
        validators: [
          new MaxFileSizeValidator({ maxSize: 2 * 1024 * 1024 }),
          new FileTypeValidator({ fileType: /^image\/(png|jpeg)$/, fallbackToMimetype: true }),   // pas de buffer : on ne peut lire que le type annoncé
        ],
      }),
    )
    fichier: Express.Multer.File,
  ) {
    return { nomStocke: fichier.filename, chemin: fichier.path, type: fichier.mimetype };
  }

  // 4. Constructeur ParseFilePipeBuilder ; fichier facultatif ; limite Multer de 1 Mo
  @Post('avatar')
  @UseInterceptors(FileInterceptor('avatar', { limits: { fileSize: 1024 * 1024 } }))
  avatar(
    @UploadedFile(
      new ParseFilePipeBuilder()
        .addFileTypeValidator({ fileType: 'image/png' })
        .build({ fileIsRequired: false, errorHttpStatusCode: HttpStatus.UNPROCESSABLE_ENTITY }),
    )
    fichier?: Express.Multer.File,
  ) {
    return fichier ? { recu: fichier.originalname, taille: fichier.size } : { recu: null, message: 'Avatar inchangé' };
  }

  // 5. Plusieurs fichiers dans le même champ (3 au maximum)
  @Post('album')
  @UseInterceptors(FilesInterceptor('photos', 3))
  album(@UploadedFiles() fichiers: Express.Multer.File[]) {
    return fichiers.map((f) => `${f.originalname} (${f.size} o)`);
  }

  // 6. Plusieurs champs de fichiers différents
  @Post('dossier')
  @UseInterceptors(FileFieldsInterceptor([{ name: 'cv', maxCount: 1 }, { name: 'diplomes', maxCount: 2 }]))
  dossier(@UploadedFiles() f: { cv?: Express.Multer.File[]; diplomes?: Express.Multer.File[] }) {
    return { cv: f.cv?.map((x) => x.originalname) ?? [], diplomes: f.diplomes?.map((x) => x.originalname) ?? [] };
  }
}
  • FileInterceptor('fichier'): un intercepteur (leçon 9.5) qui demande à Multer de lire le champ fichier. Le nom doit être exactement celui utilisé par le client.
  • @UploadedFile() injecte le fichier : originalname, mimetype, size et, par défaut (stockage en mémoire), buffer qui contient les octets.
  • Les champs texte du même formulaire arrivent dans @Body() et sont validés par un DTO comme d'habitude.
  • MaxFileSizeValidator limite la taille ; FileTypeValidator vérifie le type en lisant la signature du fichier (ses premiers octets, appelés « nombres magiques » : %PDF pour un PDF, 89 50 4E 47 pour un PNG). Avec overrideMimeType: true, fichier.mimetype est remplacé par le type réellement détecté.
Les essais

Le client de test envoie de petits fichiers dont les premiers octets sont ceux de vrais PNG, JPEG et PDF, ainsi qu'un texte et un fichier de 3 Mo :

📄 src/main.ts (extrait)

  const png = { champ: 'fichier', nom: 'Photo Sami.PNG', type: 'image/png', contenu: PNG };
  const deguise = { champ: 'fichier', nom: 'virus.png', type: 'image/png', contenu: TEXTE };
  console.log('— 1. En mémoire');
  await appel('POST', '/api/photos/memoire', { fichiers: [png] });

  console.log('\n— 2. Méthode recommandée : valider en mémoire, puis enregistrer');
  await appel('POST', '/api/photos', { champs: { legende: 'Remise des diplômes' }, fichiers: [png] });
  await appel('POST', '/api/photos', { champs: { legende: 'Sans fichier' } });
  await appel('POST', '/api/photos', { champs: { legende: 'Un PDF' }, fichiers: [{ champ: 'fichier', nom: 'cv.pdf', type: 'application/pdf', contenu: PDF }] });
  await appel('POST', '/api/photos', { champs: { legende: 'Trop gros' }, fichiers: [{ champ: 'fichier', nom: 'grand.png', type: 'image/png', contenu: GROS }] });
  await appel('POST', '/api/photos', { champs: { legende: 'x' }, fichiers: [png] });
  await appel('POST', '/api/photos', { champs: { legende: 'Texte déguisé en image' }, fichiers: [deguise] });
  await appel('POST', '/api/photos', { champs: { legende: 'PNG annoncé JPEG' }, fichiers: [{ champ: 'fichier', nom: 'photo.jpg', type: 'image/jpeg', contenu: PNG }] });
  console.log('   Fichiers dans ./uploads :', readdirSync('uploads'));

  console.log('\n— 3. Variante diskStorage');
  await appel('POST', '/api/photos/disque', { fichiers: [png] });
  await appel('POST', '/api/photos/disque', { fichiers: [deguise] });
  await appel('POST', '/api/photos/disque', { fichiers: [{ champ: 'fichier', nom: 'cv.pdf', type: 'application/pdf', contenu: PDF }] });
  console.log('   Fichiers dans ./uploads-disque :', readdirSync('uploads-disque').length);

  console.log('\n— 4. Avatar facultatif, limite Multer de 1 Mo');
  await appel('POST', '/api/photos/avatar', { fichiers: [{ champ: 'avatar', nom: 'moi.png', type: 'image/png', contenu: PNG }] });
  await appel('POST', '/api/photos/avatar', { champs: { rien: '' } });
  await appel('POST', '/api/photos/avatar', { fichiers: [{ champ: 'avatar', nom: 'moi.jpg', type: 'image/jpeg', contenu: JPEG }] });
  await appel('POST', '/api/photos/avatar', { fichiers: [{ champ: 'avatar', nom: 'grand.png', type: 'image/png', contenu: GROS }] });

  console.log('\n— 5 et 6. Plusieurs fichiers');
  const p = (n: string, champ = 'photos') => ({ champ, nom: n, type: 'image/png', contenu: PNG });
  await appel('POST', '/api/photos/album', { fichiers: [p('a.png'), p('b.png')] });
  await appel('POST', '/api/photos/album', { fichiers: [p('a.png'), p('b.png'), p('c.png'), p('d.png')] });
  await appel('POST', '/api/photos/album', { fichiers: [p('a.png', 'autre')] });
  await appel('POST', '/api/photos/dossier', { fichiers: [p('cv.pdf', 'cv'), p('licence.pdf', 'diplomes'), p('bac.pdf', 'diplomes')] });

Résultat réellement obtenu :

— 1. En mémoire
POST /api/photos/memoire → 201 {"fieldname":"fichier","originalname":"Photo Sami.PNG","mimetype":"image/png","size":216,"buffer":"Buffer de 216 octets"}

— 2. Méthode recommandée : valider en mémoire, puis enregistrer
POST /api/photos → 201 {"legende":"Remise des diplômes","nomOriginal":"Photo Sami.PNG","nomStocke":"87f5dae4-db82-4e14-86fe-c3f565aebc63.png","taille":216,"type":"image/png"}
POST /api/photos → 400 {"message":"File is required","error":"Bad Request","statusCode":400}
POST /api/photos → 400 {"message":"Validation failed (current file type is application/pdf, expected type is /^image\\/(png|jpeg)$/)","error":"Bad Request","statusCode":400}
POST /api/photos → 400 {"message":"Fichier trop volumineux (2 Mo maximum)","error":"Bad Request","statusCode":400}
POST /api/photos → 400 {"message":["legende must be longer than or equal to 2 characters"],"error":"Bad Request","statusCode":400}
POST /api/photos → 400 {"message":"Validation failed (file type could not be detected from its content; expected type is /^image\\/(png|jpeg)$/)","error":"Bad Request","statusCode":400}
POST /api/photos → 201 {"legende":"PNG annoncé JPEG","nomOriginal":"photo.jpg","nomStocke":"ce344dc4-e19c-4e3f-aa1d-a7f5be6037ad.png","taille":216,"type":"image/png"}
   Fichiers dans ./uploads : [
  '87f5dae4-db82-4e14-86fe-c3f565aebc63.png',
  'ce344dc4-e19c-4e3f-aa1d-a7f5be6037ad.png'
]

— 3. Variante diskStorage
POST /api/photos/disque → 201 {"nomStocke":"a0d3d713-fd8a-4678-a287-962af963c905.png","chemin":"uploads-disque/a0d3d713-fd8a-4678-a287-962af963c905.png","type":"image/png"}
POST /api/photos/disque → 201 {"nomStocke":"8bd23bcb-c825-49fc-8bce-8318e3eafd12.png","chemin":"uploads-disque/8bd23bcb-c825-49fc-8bce-8318e3eafd12.png","type":"image/png"}
POST /api/photos/disque → 400 {"message":"Validation failed (current file type is application/pdf, expected type is /^image\\/(png|jpeg)$/) - magic number detection failed, used mimetype fallback","error":"Bad Request","statusCode":400}
   Fichiers dans ./uploads-disque : 2

— 4. Avatar facultatif, limite Multer de 1 Mo
POST /api/photos/avatar → 201 {"recu":"moi.png","taille":216}
POST /api/photos/avatar → 201 {"recu":null,"message":"Avatar inchangé"}
POST /api/photos/avatar → 422 {"message":"Validation failed (current file type is image/jpeg, expected type is image/png)","error":"Unprocessable Entity","statusCode":422}
POST /api/photos/avatar → 413 {"message":"File too large","error":"Payload Too Large","statusCode":413}

— 5 et 6. Plusieurs fichiers
POST /api/photos/album → 201 ["a.png (216 o)","b.png (216 o)"]
POST /api/photos/album → 400 {"message":"Unexpected file field - photos","error":"Bad Request","statusCode":400}
POST /api/photos/album → 400 {"message":"Unexpected file field - autre","error":"Bad Request","statusCode":400}
POST /api/photos/dossier → 201 {"cv":["cv.pdf"],"diplomes":["licence.pdf","bac.pdf"]}
Lecture
  • Fichier absent: « File is required » (400). Trop gros: notre message (400). Mauvais type: le PDF est refusé, et le message indique le type détecté.
  • Texte déguisé en image (nom virus.png, type annoncé image/png) : refusé, car son contenu ne ressemble à aucun format connu.
  • Vrai PNG annoncé comme JPEG: accepté, car c'est bien une image autorisée, et enregistré en .png d'après le type détecté. Le nom et le type envoyés par le client ne servent qu'à l'affichage.
  • Seuls les fichiers valides ont été écrits dans uploads/, sous un nom uuid: impossible d'écraser un autre fichier ou d'injecter un chemin (../../) par le nom.
Le piège de diskStorage

Avec diskStorage, Multer écrit le fichier sur le disque avant la validation, et fichier.buffer n'existe pas. FileTypeValidator ne peut donc pas lire la signature. Sans option, il refuse tous les fichiers (« file buffer is not available »). Avec fallbackToMimetype: true, il se contente du type annoncé par le client : le texte déguisé en image est accepté et enregistré (section 3 du résultat).

Règle pratique: pour des fichiers de taille raisonnable (documents, photos de quelques Mo), gardez le stockage en mémoire, validez, puis écrivez vous-même le fichier sous un nom généré. Réservez diskStorage aux très gros fichiers (vidéos), en vérifiant le type après coup avec la bibliothèque file-type sur le fichier enregistré, et en le supprimant s'il est refusé. Dans tous les cas, fixez une limite Multer (limits.fileSize) : sans elle, un client peut envoyer un fichier énorme qui sera entièrement lu en mémoire.

Les autres cas
  • Fichier facultatif: fileIsRequired: false; le paramètre vaut alors undefined.
  • Statut d'erreur: errorHttpStatusCode (ici 422) avec ParseFilePipeBuilder.
  • Limite Multer (limits.fileSize) : Multer interrompt la lecture et NestJS répond 413 « Payload Too Large », avant même les validateurs.
  • Plusieurs fichiers: FilesInterceptor('photos', 3) et @UploadedFiles() (un tableau). Au-delà de 3, ou avec un champ inattendu : 400 « Unexpected file field ».
  • Plusieurs champs: FileFieldsInterceptor donne un objet { cv: [...], diplomes: [...] }.
Envoyer un fichier depuis un client
# curl : -F envoie un formulaire multipart, @ désigne un fichier local
curl -F "legende=Remise des diplômes" -F "fichier=@photo.png" http://localhost:3000/api/photos
// Angular (chapitre 18) : FormData, sans fixer Content-Type (le navigateur ajoute la limite « boundary »)
const donnees = new FormData();
donnees.append('legende', 'Remise des diplômes');
donnees.append('fichier', input.files[0]);
this.http.post('/api/photos', donnees).subscribe();
Activités

Activité 1 Un avatar par utilisateur

Dans le projet du TP 8, ajoutez PATCH /api/utilisateurs/moi/avatar: image PNG ou JPEG de 500 Ko au maximum, enregistrée dans stockage/avatars/<id>.png|jpg (en remplaçant l'ancienne). Testez avec curl un PNG, un PDF renommé en .png et une image de 2 Mo.

Voir le corrigé
@Patch('moi/avatar')
@UseInterceptors(FileInterceptor('avatar', { limits: { fileSize: 1024 * 1024 } }))
async avatar(
  @UploadedFile(new ParseFilePipe({ validators: [
    new MaxFileSizeValidator({ maxSize: 500 * 1024 }),
    new FileTypeValidator({ fileType: /^image\/(png|jpeg)$/, overrideMimeType: true }),
  ] }))
  fichier: Express.Multer.File,
  @Moi('id') id: number,
) {
  const ext = fichier.mimetype === 'image/png' ? 'png' : 'jpg';
  await mkdir('stockage/avatars', { recursive: true });
  for (const e of ['png', 'jpg']) await unlink(`stockage/avatars/${id}.${e}`).catch(() => undefined);
  await writeFile(`stockage/avatars/${id}.${ext}`, fichier.buffer);
  return { avatar: `${id}.${ext}` };
}

Le PDF renommé est refusé (signature %PDF) ; l'image de 2 Mo dépasse la limite Multer (413) ; une image de 700 Ko passe Multer mais pas le validateur (400).

Activité 2 Quel statut ?

Pour la route POST /api/photos/avatar de la leçon, donnez le statut : (a) aucun fichier ; (b) un JPEG de 10 Ko ; (c) un PNG de 3 Mo ; (d) un fichier dans un champ nommé photo au lieu de avatar.

Voir le corrigé

(a) 201, le fichier est facultatif. (b) 422 (type refusé, statut choisi avec errorHttpStatusCode). (c) 413 (limite Multer de 1 Mo). (d) 400 « Unexpected file field - photo » : Multer refuse les champs de fichier qu'on ne lui a pas annoncés.

Activité 3 Un validateur personnalisé

Écrivez un validateur NomDeFichierValidator (classe qui étend FileValidator) qui refuse les noms d'origine de plus de 100 caractères ou contenant /, \ ou ... Ajoutez-le au ParseFilePipe.

Voir le corrigé
import { FileValidator } from '@nestjs/common';

export class NomDeFichierValidator extends FileValidator<Record<string, never>> {
  constructor() { super({}); }
  isValid(fichier?: Express.Multer.File): boolean {
    const nom = fichier?.originalname ?? '';
    return nom.length > 0 && nom.length <= 100 && !/[\\/]|\.\./.test(nom);
  }
  buildErrorMessage(): string {
    return 'Nom de fichier invalide';
  }
}

Même si le nom d'origine n'est jamais utilisé comme chemin (on stocke sous un uuid), le garder propre évite des surprises à l'affichage et dans l'en-tête Content-Disposition (leçon 15.2).

Activité 4 Mémoire ou disque ?

Pour chaque cas, stockage en mémoire ou diskStorage, et pourquoi ? (a) Photos de profil (1 Mo au plus). (b) Vidéos de cours (jusqu'à 2 Go). (c) Bulletins PDF (5 Mo au plus) déposés par des stagiaires.

Voir le corrigé

(a) et (c) : mémoire, validation par signature, puis écriture. Quelques Mo par requête restent raisonnables. (b) : diskStorage (2 Go en mémoire ferait tomber le serveur), avec limits.fileSize, puis vérification du type sur le fichier écrit (file-type) et suppression en cas de refus. Pour de tels volumes, on envoie souvent directement vers un stockage objet (S3, MinIO) avec une URL signée, sans passer par l'API.

À retenir

  • Fichiers en multipart/form-data ; @UseInterceptors(FileInterceptor('champ')) + @UploadedFile().
  • ParseFilePipe : MaxFileSizeValidator et FileTypeValidator (signature du contenu, overrideMimeType).
  • Ne jamais faire confiance au nom, à l'extension ni au type annoncés par le client : stocker sous un uuid.
  • diskStorage écrit avant la validation et n'a pas de buffer : préférer la mémoire pour les fichiers raisonnables.
  • limits.fileSize de Multer → 413 ; FilesInterceptor / FileFieldsInterceptor pour plusieurs fichiers.

Cet article vous a-t-il aidé ?