使用 Express 中的 Multer 中间件实现文件上传

引言

大家好，欢迎来到今天的讲座！今天我们要聊的是如何使用 Express 和 Multer 中间件来实现文件上传。如果你曾经尝试过处理文件上传，你可能会觉得这是一件既有趣又令人头疼的事情。好消息是，有了 Multer，这一切都变得简单多了！我们不仅会讲解理论知识，还会通过实际代码示例来帮助你更好地理解。准备好了吗？让我们开始吧！

什么是 Express？

在深入探讨 Multer 之前，我们先简单回顾一下 Express。Express 是一个基于 Node.js 的轻量级 Web 框架，它提供了许多强大的功能，可以帮助我们快速构建 Web 应用程序。它的核心理念是“约定优于配置”，这意味着你可以用最少的代码实现复杂的功能。

Express 的特点

简洁易用：Express 的 API 非常简洁，学习曲线平缓。
灵活扩展：通过中间件和插件，你可以轻松扩展 Express 的功能。
高效性能：Express 本身非常轻量，运行效率高。
社区支持：庞大的开发者社区为 Express 提供了丰富的资源和文档。

安装 Express

如果你还没有安装 Express，可以通过以下命令进行安装：

npm install express

接下来，我们创建一个简单的 Express 应用程序：

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello, World!');
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

这段代码启动了一个简单的 HTTP 服务器，监听端口 3000，并在访问根路径时返回 "Hello, World!"。是不是很简单呢？

什么是 Multer？

现在我们已经了解了 Express，接下来该轮到 Multer 登场了。Multer 是一个专门用于处理 multipart/form-data 编码的中间件，主要用于文件上传。它可以帮助我们将上传的文件保存到服务器上，并提供一些有用的信息，比如文件名、大小等。

Multer 的特点

简单易用：只需几行代码即可实现文件上传。
灵活配置：可以根据需要自定义文件存储位置、文件名格式等。
内置验证：可以设置文件类型、大小限制等，确保上传的文件符合要求。
异步处理：支持异步操作，不会阻塞主线程。

安装 Multer

同样，我们可以通过 npm 来安装 Multer：

npm install multer

安装完成后，我们就可以在 Express 应用中使用它了。

文件上传的基本原理

在深入讲解 Multer 的具体用法之前，我们先了解一下文件上传的基本原理。文件上传通常涉及到以下几个步骤：

前端表单：用户通过 HTML 表单选择要上传的文件。
请求发送：浏览器将文件作为 multipart/form-data 编码的数据发送给服务器。
服务器处理：服务器接收到数据后，解析并保存文件。
响应反馈：服务器向客户端返回处理结果。

前端表单

首先，我们需要在前端创建一个表单，允许用户选择文件并提交。这里是一个简单的 HTML 表单示例：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>File Upload</title>
</head>
<body>
  <h1>Upload a File</h1>
  <form action="/upload" method="POST" enctype="multipart/form-data">
    <input type="file" name="avatar" />
    <button type="submit">Upload</button>
  </form>
</body>
</html>

注意这里的 enctype="multipart/form-data" 属性，它是文件上传的关键。如果没有这个属性，浏览器会以默认的 application/x-www-form-urlencoded 编码方式发送数据，而这种方式无法处理文件。

请求发送

当用户点击提交按钮时，浏览器会将表单数据（包括文件）发送到指定的 URL（在这个例子中是 /upload）。服务器端需要处理这个 POST 请求，并解析其中的文件数据。

服务器处理

服务器接收到请求后，需要使用 Multer 来解析 multipart/form-data 编码的数据。Multer 会自动将文件保存到指定的位置，并将相关信息传递给路由处理函数。

响应反馈

最后，服务器会向客户端返回一个响应，告知文件上传是否成功。我们可以根据需要返回不同的状态码或消息。

使用 Multer 实现文件上传

现在我们已经了解了文件上传的基本原理，接下来我们来看看如何使用 Multer 来实现文件上传。我们将分几个步骤来完成这个过程。

1. 创建 Multer 实例

首先，我们需要创建一个 Multer 实例，并配置文件存储的相关选项。Multer 提供了两种主要的存储方式：内存存储和磁盘存储。

内存存储

内存存储将文件保存在内存中，适合处理小文件或临时文件。我们可以通过 memoryStorage 方法来创建内存存储实例：

const multer = require('multer');
const upload = multer({ storage: multer.memoryStorage() });

磁盘存储

磁盘存储将文件直接保存到磁盘上，适合处理大文件或需要长期保存的文件。我们可以通过 diskStorage 方法来自定义文件存储路径和文件名格式：

const multer = require('multer');

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, 'uploads/'); // 指定文件保存的目录
  },
  filename: function (req, file, cb) {
    cb(null, Date.now() + '-' + file.originalname); // 自定义文件名
  }
});

const upload = multer({ storage: storage });

2. 设置文件过滤器

有时我们可能只希望接受特定类型的文件，或者对文件大小进行限制。Multer 提供了 fileFilter 和 limits 选项来实现这些需求。

文件过滤器

fileFilter 是一个回调函数，用于决定是否接受某个文件。我们可以通过检查文件的 MIME 类型或扩展名来实现过滤：

const upload = multer({
  storage: storage,
  fileFilter: function (req, file, cb) {
    if (file.mimetype === 'image/jpeg' || file.mimetype === 'image/png') {
      cb(null, true); // 接受文件
    } else {
      cb(new Error('Only JPEG and PNG files are allowed!'), false); // 拒绝文件
    }
  }
});

文件大小限制

limits 选项允许我们设置文件大小的限制。例如，我们可以限制单个文件的最大大小为 1MB：

const upload = multer({
  storage: storage,
  limits: {
    fileSize: 1 * 1024 * 1024 // 1MB
  }
});

3. 处理文件上传请求

接下来，我们需要在 Express 路由中使用 Multer 中间件来处理文件上传请求。Multer 提供了多种方法来处理不同类型的文件上传，包括单个文件、多个文件以及带有其他字段的表单。

单个文件上传

如果表单中只有一个文件输入字段，我们可以使用 single 方法来处理单个文件上传：

app.post('/upload', upload.single('avatar'), (req, res) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded.');
  }

  console.log(req.file); // 打印文件信息
  res.send('File uploaded successfully!');
});

req.file 包含了上传文件的相关信息，比如文件名、路径、大小等。我们可以在控制台中打印出来查看。

多个文件上传

如果表单中有多个文件输入字段，我们可以使用 array 方法来处理多个文件上传：

app.post('/upload', upload.array('photos', 5), (req, res) => {
  if (!req.files) {
    return res.status(400).send('No files uploaded.');
  }

  console.log(req.files); // 打印多个文件信息
  res.send('Files uploaded successfully!');
});

req.files 是一个数组，包含了所有上传文件的信息。我们可以通过遍历这个数组来处理每个文件。

带有其他字段的表单

有时候，表单中不仅包含文件，还包含其他文本字段。我们可以使用 fields 方法来处理这种情况：

app.post('/upload', upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'photos', maxCount: 5 }
]), (req, res) => {
  console.log(req.files); // 打印文件信息
  console.log(req.body);  // 打印其他字段信息
  res.send('Files and fields uploaded successfully!');
});

req.files 包含了所有上传文件的信息，而 req.body 包含了其他文本字段的值。我们可以在同一个请求中同时处理文件和文本数据。

4. 错误处理

在实际应用中，文件上传可能会遇到各种错误，比如文件过大、文件类型不匹配等。为了提高用户体验，我们需要对这些错误进行适当的处理。

Multer 会在发生错误时调用路由处理函数中的 next 函数，并传递一个错误对象。我们可以在路由处理函数中捕获这个错误，并返回相应的错误信息：

app.post('/upload', upload.single('avatar'), (req, res, next) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded.');
  }

  try {
    // 处理文件上传逻辑
    res.send('File uploaded successfully!');
  } catch (error) {
    next(error); // 将错误传递给全局错误处理中间件
  }
});

// 全局错误处理中间件
app.use((err, req, res, next) => {
  console.error(err.message);
  res.status(500).send('Something went wrong!');
});

通过这种方式，我们可以确保即使在文件上传过程中出现错误，也不会导致整个应用程序崩溃。

进阶技巧

掌握了基本的文件上传功能后，我们还可以进一步优化和扩展我们的应用程序。下面是一些进阶技巧，帮助你更好地使用 Multer。

1. 文件重命名

有时候我们希望为上传的文件生成唯一的名称，以避免文件名冲突。我们可以通过 filename 回调函数来自定义文件名格式。例如，我们可以使用时间戳和随机字符串来生成唯一的文件名：

const crypto = require('crypto');

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, 'uploads/');
  },
  filename: function (req, file, cb) {
    const uniqueSuffix = crypto.randomBytes(6).toString('hex');
    cb(null, `${Date.now()}-${uniqueSuffix}-${file.originalname}`);
  }
});

这样，即使两个用户上传了相同名称的文件，它们也会被保存为不同的文件名。

2. 文件压缩

对于某些类型的文件，比如图片，我们可以使用第三方库（如 sharp）来压缩文件，减少存储空间和带宽消耗。以下是一个简单的图片压缩示例：

const sharp = require('sharp');

app.post('/upload', upload.single('avatar'), async (req, res) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded.');
  }

  try {
    // 压缩图片
    await sharp(req.file.path)
      .resize(800, 600)
      .toFormat('jpeg')
      .toFile(`compressed-${req.file.filename}`);

    res.send('File compressed and uploaded successfully!');
  } catch (error) {
    next(error);
  }
});

通过这种方式，我们可以显著减小图片的体积，同时保持较高的质量。

3. 文件上传进度

在处理大文件时，用户可能会想知道文件上传的进度。我们可以通过 busboy 库来实现文件上传进度的实时反馈。以下是一个简单的示例：

const busboy = require('connect-busboy');
app.use(busboy());

app.post('/upload', (req, res) => {
  let totalSize = 0;
  let uploadedSize = 0;

  const busboyInstance = req.busboy;

  busboyInstance.on('file', (fieldname, file, filename) => {
    file.on('data', (chunk) => {
      uploadedSize += chunk.length;
      console.log(`Progress: ${Math.round((uploadedSize / totalSize) * 100)}%`);
    });

    file.on('end', () => {
      console.log('File upload complete!');
    });
  });

  busboyInstance.on('field', (key, value) => {
    // 处理其他表单字段
  });

  busboyInstance.on('finish', () => {
    res.send('File uploaded successfully!');
  });

  req.pipe(busboyInstance);
});

通过这种方式，我们可以在文件上传过程中实时监控进度，并向用户反馈上传状态。

4. 文件删除

有时候我们可能需要在上传完成后删除某些文件，比如临时文件或不再需要的备份文件。我们可以使用 fs 模块来实现文件删除功能：

const fs = require('fs').promises;

app.post('/upload', upload.single('avatar'), async (req, res, next) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded.');
  }

  try {
    // 处理文件上传逻辑
    res.send('File uploaded successfully!');

    // 删除文件
    await fs.unlink(req.file.path);
  } catch (error) {
    next(error);
  }
});

通过这种方式，我们可以确保在不需要时及时清理文件，避免占用过多的磁盘空间。

总结

今天我们详细讲解了如何使用 Express 和 Multer 中间件来实现文件上传。从基本的文件上传流程到进阶的优化技巧，我们涵盖了多个方面的内容。希望这篇文章能够帮助你更好地理解和掌握文件上传的实现方法。

当然，文件上传只是 Web 开发中的一个小部分。在实际项目中，你可能会遇到更多复杂的场景和需求。不过，只要你掌握了基础知识，并不断实践和探索，相信你一定能够应对各种挑战。

如果你有任何问题或想法，欢迎在评论区留言。我们下次再见！😊

附录：常用配置参数表

参数名	描述	示例值
`storage`	指定文件存储方式（内存或磁盘）	`multer.memoryStorage()`
`fileFilter`	文件过滤器，用于决定是否接受某个文件	`function (req, file, cb)`
`limits`	文件大小和其他限制条件	`{ fileSize: 1 * 1024 * 1024 }`
`destination`	指定文件保存的目录（仅适用于磁盘存储）	`'uploads/'`
`filename`	指定文件名格式（仅适用于磁盘存储）	`function (req, file, cb)`
`maxCount`	指定最多允许上传的文件数量（仅适用于 `array` 和 `fields`）	`5`

附录：常见错误及解决方案

错误描述	解决方案
文件上传失败，提示 "No file uploaded."	检查表单是否设置了 `enctype="multipart/form-data"`，并确保文件输入字段的 `name` 属性与 Multer 中的配置一致。
文件上传成功，但无法找到文件	检查文件存储路径是否正确，确保服务器有写权限。
文件上传失败，提示 "Unexpected field"	检查表单中的字段名是否与 Multer 中的配置匹配，确保没有多余的字段。
文件上传失败，提示 "File too large"	检查 `limits` 中的 `fileSize` 配置，确保文件大小不超过限制。
文件上传失败，提示 "Unsupported file type"	检查 `fileFilter` 中的文件类型过滤规则，确保文件类型符合要求。

希望这篇文章对你有所帮助！如果你有任何问题或建议，欢迎随时交流。祝你在文件上传的世界里玩得开心！🎉