title: NestJS文件上传
description: 深入学习NestJS中的文件上传实现，包括文件上传配置、multer集成、文件验证和文件存储
keywords: NestJS, 文件上传, multer, 文件验证, 文件存储, 图片上传

NestJS文件上传

学习目标

通过本章节的学习，你将能够：

  • 理解文件上传的基本概念和工作原理
  • 掌握NestJS中文件上传的配置方法
  • 集成multer实现文件上传功能
  • 实现文件验证，包括文件类型、大小等
  • 配置不同的文件存储策略
  • 构建完整的文件上传系统，支持图片上传等功能
  • 理解文件上传的最佳实践和常见问题解决方案

核心知识点

文件上传基础

文件上传是Web应用中常见的功能，允许用户将本地文件上传到服务器。文件上传的主要步骤包括：

  1. 客户端选择文件并提交表单
  2. 服务器接收文件数据
  3. 服务器验证文件（类型、大小等）
  4. 服务器存储文件
  5. 服务器返回文件访问路径或其他信息

Multer

Multer是一个Node.js中间件，用于处理multipart/form-data类型的表单数据，主要用于文件上传。Multer的主要特性包括：

  • 支持多种存储引擎（磁盘、内存等）
  • 支持文件过滤和验证
  • 支持多文件上传
  • 支持文件重命名
  • 支持文件大小限制

NestJS文件上传配置

NestJS通过@nestjs/platform-express模块提供了对Express中间件的支持，包括multer。NestJS中文件上传的主要配置包括：

  • 配置multer存储选项
  • 设置文件大小限制
  • 配置文件类型验证
  • 设置文件存储路径
  • 配置文件命名策略

文件验证

文件验证是确保上传文件符合要求的重要步骤，主要包括：

  • 文件类型验证：确保上传的是允许的文件类型
  • 文件大小验证：限制文件大小，防止恶意上传
  • 文件内容验证：确保文件内容符合要求
  • 文件命名验证：确保文件名符合规范

文件存储策略

常见的文件存储策略包括：

  • 本地存储：存储在服务器本地文件系统
  • 云存储：存储在AWS S3、Azure Blob Storage等云服务
  • 数据库存储：存储在数据库中（通常用于小文件）
  • CDN存储：结合CDN加速文件访问

实用案例分析

案例：图片上传系统

我们将构建一个完整的图片上传系统，支持单文件上传、多文件上传、文件验证和文件存储。

1. 安装依赖

首先，我们需要安装必要的依赖：

npm install multer @types/multer

2. 配置文件上传模块

创建一个文件上传模块，配置multer：

// src/file/file.module.ts
import { Module } from '@nestjs/common';
import { FileService } from './file.service';
import { FileController } from './file.controller';
import { MulterModule } from '@nestjs/platform-express';
import { diskStorage } from 'multer';
import { extname, join } from 'path';

@Module({
  imports: [
    MulterModule.register({
      storage: diskStorage({
        destination: join(__dirname, '..', '..', 'uploads'),
        filename: (req, file, callback) => {
          const randomName = Array(32)
            .fill(null)
            .map(() => Math.round(Math.random() * 16).toString(16))
            .join('');
          callback(null, `${randomName}${extname(file.originalname)}`);
        },
      }),
      limits: {
        fileSize: 1024 * 1024 * 5, // 5MB
      },
      fileFilter: (req, file, callback) => {
        const allowedExtensions = ['.jpg', '.jpeg', '.png', '.gif'];
        const ext = extname(file.originalname).toLowerCase();
        if (allowedExtensions.includes(ext)) {
          callback(null, true);
        } else {
          callback(new Error('Only image files are allowed!'), false);
        }
      },
    }),
  ],
  providers: [FileService],
  controllers: [FileController],
})
export class FileModule {}

3. 创建文件服务

创建一个文件服务，处理文件上传和存储：

// src/file/file.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { existsSync, unlinkSync, readdirSync } from 'fs';
import { join } from 'path';

@Injectable()
export class FileService {
  private uploadsDir = join(__dirname, '..', '..', 'uploads');

  // 获取文件列表
  async getFiles() {
    if (!existsSync(this.uploadsDir)) {
      return [];
    }
    return readdirSync(this.uploadsDir);
  }

  // 删除文件
  async deleteFile(filename: string) {
    const filePath = join(this.uploadsDir, filename);
    if (!existsSync(filePath)) {
      throw new NotFoundException('File not found');
    }
    unlinkSync(filePath);
    return { message: 'File deleted successfully' };
  }

  // 获取文件路径
  getFilePath(filename: string) {
    return join(this.uploadsDir, filename);
  }

  // 检查文件是否存在
  fileExists(filename: string) {
    return existsSync(join(this.uploadsDir, filename));
  }
}

4. 创建文件控制器

创建一个文件控制器，处理文件上传请求：

// src/file/file.controller.ts
import { Controller, Post, Get, Delete, Param, UploadedFile, UploadedFiles, UseInterceptors, BadRequestException } from '@nestjs/common';
import { FileInterceptor, FilesInterceptor } from '@nestjs/platform-express';
import { FileService } from './file.service';

@Controller('file')
export class FileController {
  constructor(private fileService: FileService) {}

  // 单文件上传
  @Post('upload')
  @UseInterceptors(FileInterceptor('file'))
  async uploadFile(@UploadedFile() file: Express.Multer.File) {
    if (!file) {
      throw new BadRequestException('No file uploaded');
    }
    return {
      filename: file.filename,
      originalname: file.originalname,
      size: file.size,
      mimetype: file.mimetype,
      path: `/uploads/${file.filename}`,
    };
  }

  // 多文件上传
  @Post('upload-multiple')
  @UseInterceptors(FilesInterceptor('files', 10)) // 最多上传10个文件
  async uploadMultipleFiles(@UploadedFiles() files: Express.Multer.File[]) {
    if (!files || files.length === 0) {
      throw new BadRequestException('No files uploaded');
    }
    return files.map(file => ({
      filename: file.filename,
      originalname: file.originalname,
      size: file.size,
      mimetype: file.mimetype,
      path: `/uploads/${file.filename}`,
    }));
  }

  // 获取文件列表
  @Get('list')
  async getFiles() {
    const files = await this.fileService.getFiles();
    return files.map(filename => ({
      filename,
      path: `/uploads/${filename}`,
    }));
  }

  // 删除文件
  @Delete('delete/:filename')
  async deleteFile(@Param('filename') filename: string) {
    return this.fileService.deleteFile(filename);
  }
}

5. 配置静态文件服务

在main.ts中配置静态文件服务，使上传的文件可以通过HTTP访问：

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { join } from 'path';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // 配置静态文件服务
  app.useStaticAssets(join(__dirname, '..', 'uploads'), {
    prefix: '/uploads/',
  });
  
  await app.listen(3000);
}
bootstrap();

6. 创建上传目录

确保上传目录存在：

mkdir -p uploads

7. 自定义文件拦截器

创建一个自定义的文件拦截器，实现更复杂的文件验证逻辑：

// src/file/interceptors/image-upload.interceptor.ts
import { FileInterceptor } from '@nestjs/platform-express';
import { diskStorage } from 'multer';
import { extname, join } from 'path';

// 生成随机文件名
const generateFileName = (req, file, callback) => {
  const randomName = Array(32)
    .fill(null)
    .map(() => Math.round(Math.random() * 16).toString(16))
    .join('');
  callback(null, `${randomName}${extname(file.originalname)}`);
};

// 图片文件过滤器
const imageFileFilter = (req, file, callback) => {
  const allowedExtensions = ['.jpg', '.jpeg', '.png', '.gif'];
  const ext = extname(file.originalname).toLowerCase();
  if (allowedExtensions.includes(ext)) {
    callback(null, true);
  } else {
    callback(new Error('Only image files are allowed!'), false);
  }
};

export const ImageUploadInterceptor = (fieldName: string = 'file') => {
  return FileInterceptor(fieldName, {
    storage: diskStorage({
      destination: join(__dirname, '..', '..', '..', 'uploads'),
      filename: generateFileName,
    }),
    limits: {
      fileSize: 1024 * 1024 * 5, // 5MB
    },
    fileFilter: imageFileFilter,
  });
};

8. 使用自定义文件拦截器

在控制器中使用自定义文件拦截器：

// src/file/file.controller.ts (续)
import { ImageUploadInterceptor } from './interceptors/image-upload.interceptor';

// ... 其他代码

  // 使用自定义图片上传拦截器
  @Post('upload-image')
  @UseInterceptors(ImageUploadInterceptor('image'))
  async uploadImage(@UploadedFile() file: Express.Multer.File) {
    if (!file) {
      throw new BadRequestException('No file uploaded');
    }
    return {
      filename: file.filename,
      originalname: file.originalname,
      size: file.size,
      mimetype: file.mimetype,
      path: `/uploads/${file.filename}`,
    };
  }

// ... 其他代码

9. 集成云存储（以AWS S3为例）

如果需要将文件存储到云服务，可以集成AWS S3：

npm install aws-sdk multer-s3
npm install --save-dev @types/multer-s3

配置S3存储：

// src/file/config/s3.config.ts
import * as AWS from 'aws-sdk';
import * as multerS3 from 'multer-s3';
import { extname } from 'path';

// 配置AWS
AWS.config.update({
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_REGION,
});

const s3 = new AWS.S3();

// 生成S3存储配置
export const s3Storage = multerS3({
  s3: s3,
  bucket: process.env.AWS_BUCKET_NAME,
  acl: 'public-read',
  key: (req, file, callback) => {
    const randomName = Array(32)
      .fill(null)
      .map(() => Math.round(Math.random() * 16).toString(16))
      .join('');
    callback(null, `${randomName}${extname(file.originalname)}`);
  },
});

// 图片文件过滤器
export const imageFileFilter = (req, file, callback) => {
  const allowedExtensions = ['.jpg', '.jpeg', '.png', '.gif'];
  const ext = extname(file.originalname).toLowerCase();
  if (allowedExtensions.includes(ext)) {
    callback(null, true);
  } else {
    callback(new Error('Only image files are allowed!'), false);
  }
};

使用S3存储：

// src/file/file.module.ts (续)
import { s3Storage, imageFileFilter } from './config/s3.config';

// ... 其他代码

@Module({
  imports: [
    MulterModule.register({
      storage: process.env.NODE_ENV === 'production' ? s3Storage : diskStorage({
        destination: join(__dirname, '..', '..', 'uploads'),
        filename: (req, file, callback) => {
          const randomName = Array(32)
            .fill(null)
            .map(() => Math.round(Math.random() * 16).toString(16))
            .join('');
          callback(null, `${randomName}${extname(file.originalname)}`);
        },
      }),
      limits: {
        fileSize: 1024 * 1024 * 5, // 5MB
      },
      fileFilter: imageFileFilter,
    }),
  ],
  // ... 其他代码
})
export class FileModule {}

代码优化建议

  1. 文件存储优化：

    • 根据环境选择合适的存储策略（开发环境使用本地存储，生产环境使用云存储）
    • 实现存储策略的抽象，便于切换不同的存储后端
    • 考虑使用CDN加速静态文件访问
    • 实现文件压缩和优化，减少存储和传输成本

  2. 文件验证优化：

    • 实现更严格的文件类型验证，不仅检查扩展名，还要检查文件内容
    • 使用文件签名验证，确保文件类型的真实性
    • 实现病毒扫描，确保上传的文件安全
    • 对上传的图片进行尺寸和质量验证

  3. 性能优化：

    • 实现文件上传进度条
    • 使用流式上传，减少内存使用
    • 实现文件分块上传，支持大文件上传
    • 配置适当的超时设置

  4. 安全性优化：

    • 防止路径遍历攻击，确保文件存储在指定目录
    • 实现文件访问控制，确保只有授权用户可以访问文件
    • 对上传的文件进行重命名，避免文件名冲突和恶意文件名
    • 限制上传频率，防止DoS攻击

  5. 可靠性优化：

    • 实现文件上传失败的重试机制
    • 记录文件上传日志，便于故障排查
    • 实现文件备份和恢复机制
    • 监控文件存储使用情况，避免存储空间耗尽

常见问题与解决方案

1. 文件上传大小限制

问题：上传大文件时遇到大小限制

解决方案：

  • 配置multer的limits.fileSize选项
  • 配置Express的limit选项
  • 考虑使用分块上传
  • 实现文件大小验证和提示

2. 文件类型验证

问题：用户上传了不允许的文件类型

解决方案：

  • 使用multer的fileFilter选项
  • 同时检查文件扩展名和MIME类型
  • 使用文件签名验证文件类型
  • 实现自定义的文件类型验证逻辑

3. 文件存储路径

问题：文件存储路径配置不当，导致文件无法访问

解决方案：

  • 使用绝对路径存储文件
  • 正确配置静态文件服务
  • 确保存储目录存在且有写权限
  • 测试文件上传和访问路径

4. 文件命名冲突

问题：上传的文件与现有文件同名，导致文件覆盖

解决方案：

  • 生成随机文件名
  • 在文件名中包含时间戳
  • 实现文件存在性检查
  • 使用UUID等唯一标识符作为文件名

5. 云存储集成

问题：集成云存储时遇到配置问题

解决方案：

  • 确保云服务的凭证正确配置
  • 确保存储桶存在且有正确的权限
  • 测试云存储的上传和下载功能
  • 实现错误处理和重试机制

小结

本章节我们学习了NestJS中的文件上传实现，包括：

  • 文件上传的基本概念和工作原理
  • NestJS中文件上传的配置方法
  • multer的集成和使用
  • 文件验证的实现，包括文件类型、大小等
  • 不同的文件存储策略，包括本地存储和云存储
  • 自定义文件拦截器的实现
  • 文件上传的最佳实践和常见问题解决方案

通过这些知识，你可以构建完整、可靠的文件上传系统，支持图片上传等功能，满足不同应用场景的需求。

互动问答

  1. 问题：文件上传的基本流程是什么？
    答案：文件上传的基本流程包括：1. 客户端选择文件并提交表单；2. 服务器接收文件数据；3. 服务器验证文件；4. 服务器存储文件；5. 服务器返回文件访问路径或其他信息。

  2. 问题：NestJS中如何实现文件上传？
    答案：通过以下步骤实现文件上传：1. 安装multer依赖；2. 配置MulterModule；3. 使用FileInterceptor或FilesInterceptor装饰器；4. 在控制器中处理上传的文件；5. 配置静态文件服务（如果使用本地存储）。

  3. 问题：如何验证上传的文件？
    答案：可以通过以下方式验证文件：1. 使用multer的fileFilter选项；2. 检查文件扩展名；3. 检查文件MIME类型；4. 检查文件大小；5. 实现自定义验证逻辑。

  4. 问题：常见的文件存储策略有哪些？
    答案：常见的文件存储策略包括：1. 本地存储：存储在服务器本地文件系统；2. 云存储：存储在AWS S3、Azure Blob Storage等云服务；3. 数据库存储：存储在数据库中（通常用于小文件）；4. CDN存储：结合CDN加速文件访问。

  5. 问题：如何处理大文件上传？
    答案：处理大文件上传的方法包括：1. 配置适当的文件大小限制；2. 使用分块上传；3. 实现上传进度条；4. 使用流式上传减少内存使用；5. 配置适当的超时设置。

实践作业

  1. 作业1：实现一个完整的图片上传系统，支持图片预览、压缩和水印

  2. 作业2：集成AWS S3或其他云存储服务，实现云存储的文件上传

  3. 作业3：实现文件上传的权限控制，确保只有授权用户可以上传和访问文件

  4. 作业4：实现文件上传的日志记录和监控，包括上传次数、文件大小等指标

  5. 作业5：构建一个完整的媒体库系统，支持文件上传、分类、搜索和管理

通过完成这些作业，你将能够更加深入地理解文件上传的实现细节，为构建功能完整的应用打下坚实的基础。

« 上一篇 17-caching 下一篇 » 19-websockets
↑