À propos de ce cours
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 avecimport type(exemple :import type { Cache } from 'cache-manager'), sinon erreur TS1272 ;"types": ["node", "jest"]: le typeExpress.Multer.Filen'est pas chargé automatiquement. Ajoutez"multer"à cette liste danstsconfig.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"]
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 champfichier. Le nom doit être exactement celui utilisé par le client.@UploadedFile()injecte le fichier :originalname,mimetype,sizeet, par défaut (stockage en mémoire),bufferqui contient les octets.- Les champs texte du même formulaire arrivent dans
@Body()et sont validés par un DTO comme d'habitude. MaxFileSizeValidatorlimite la taille ;FileTypeValidatorvérifie le type en lisant la signature du fichier (ses premiers octets, appelés « nombres magiques » :%PDFpour un PDF,89 50 4E 47pour un PNG). AvecoverrideMimeType: true,fichier.mimetypeest 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
.pngd'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 nomuuid: 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 alorsundefined. - Statut d'erreur:
errorHttpStatusCode(ici 422) avecParseFilePipeBuilder. - 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:
FileFieldsInterceptordonne 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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !