Egg.js文件上传与下载：Multipart表单处理深度解析

Egg.js文件上传与下载：Multipart表单处理深度解析

【免费下载链接】examples Store all egg examples in one place 项目地址: https://gitcode.com/gh_mirrors/examples109/examples

Egg.js作为企业级Node.js框架，提供了强大的Multipart表单处理能力，让文件上传与下载功能的开发变得简单高效。本文将从基础配置到高级应用，全面解析Egg.js中的文件处理机制，帮助开发者快速掌握这一核心技能。

一、Multipart表单处理核心配置

Egg.js通过内置的multipart插件实现文件上传功能，在config/config.default.js中可以进行全局配置：

exports.multipart = {
  mode: 'file',  // 文件模式：直接保存到磁盘
  fileSize: '50mb',  // 单个文件大小限制
  whitelist: ['.jpg', '.jpeg', '.png', '.gif'],  // 允许上传的文件类型
};

配置文件路径：multipart-file-mode/config/config.default.js

二、快速实现多文件上传功能

2.1 核心控制器实现

Egg.js提供了ctx.multipart()方法处理文件上传，以下是多文件上传的完整实现：

async upload() {
  // 创建multipart流处理器
  const parts = this.ctx.multipart({ autoFields: true });
  const files = [];
  
  let stream;
  // 遍历所有文件流
  while ((stream = await parts()) != null) {
    const filename = stream.filename.toLowerCase();
    // 构建保存路径
    const target = path.join(this.config.baseDir, 'app/public', filename);
    // 流式写入文件
    const writeStream = fs.createWriteStream(target);
    await pipeline(stream, writeStream);
    files.push(filename);
  }
  
  // 渲染上传结果页
  await this.ctx.render('page/multiple_result.html', {
    fields: Object.keys(parts.field).map(key => ({ key, value: parts.field[key] })),
    files,
  });
}

控制器路径：multipart/app/controller/multiple.js

2.2 支持的上传模式

Egg.js提供两种上传模式：

• file模式：直接保存文件到磁盘（默认）
• stream模式：获取文件流自行处理（适合云存储场景）

图：Egg.js文件上传处理流程示意图

三、文件下载功能实现

3.1 基础文件下载

通过ctx.attachment()和ctx.body实现文件下载：

async download() {
  const filename = 'example.jpg';
  const filePath = path.join(this.config.baseDir, 'app/public', filename);
  
  // 设置响应头，触发浏览器下载
  this.ctx.attachment(filename);
  this.ctx.body = fs.createReadStream(filePath);
}

3.2 断点续传支持

Egg.js结合range请求头可以轻松实现断点续传功能，特别适合大文件下载场景。

四、实用技巧与最佳实践

4.1 文件类型验证

在上传前进行文件类型验证，增强安全性：

const allowedTypes = ['.jpg', '.png', '.pdf'];
const ext = path.extname(filename);
if (!allowedTypes.includes(ext)) {
  this.ctx.throw(400, `不支持的文件类型: ${ext}`);
}

4.2 上传进度显示

结合前端XMLHttpRequest可以实现上传进度条，提升用户体验。

4.3 测试用例编写

Egg.js提供了完整的测试支持，文件上传测试示例：

it('should upload multiple files', async () => {
  const result = await app.httpRequest()
    .post('/upload/multiple')
    .attach('file1', path.join(__dirname, 'kfc.jpeg'))
    .attach('file2', path.join(__dirname, 'mc.jpeg'))
    .expect(200);
});

测试文件路径：multipart/test/index.test.js

五、常见问题解决方案

1. 文件大小限制：通过fileSize配置调整，单位支持kb、mb、gb
2. 临时文件清理：设置cleanSchedule定时清理未处理的临时文件
3. 大文件处理：使用流式处理避免内存溢出
4. 跨域上传：配置cors插件支持跨域请求

总结

Egg.js的Multipart表单处理模块为文件上传下载提供了完整解决方案，从基础配置到高级功能，都能满足企业级应用的需求。通过本文介绍的方法，开发者可以快速实现安全、高效的文件处理功能，为应用添加强大的媒体管理能力。

要开始使用这些功能，只需克隆示例项目：

git clone https://gitcode.com/gh_mirrors/examples109/examples
cd examples/multipart
npm install
npm run dev

探索更多示例代码，可查看项目中的multipart/和multipart-file-mode/目录，里面包含了各种文件处理场景的完整实现。

【免费下载链接】examples Store all egg examples in one place 项目地址: https://gitcode.com/gh_mirrors/examples109/examples