本教程详细介绍了如何在Node.js Express应用中处理HTML表单提交的文件上传，并将其存储到服务器的本地文件系统。内容涵盖前端HTML表单的关键配置，后端Express环境所需的`express-fileupload`中间件集成，以及在路由中接收、处理和保存上传文件的具体实现步骤，旨在帮助开发者构建可靠的文件上传功能。
在现代Web应用中，用户上传文件（如图片、文档）是一个常见需求。本文将指导您如何使用Node.js和Express框架，结合express-fileupload中间件，安全高效地实现这一功能。
1. 前端HTML表单配置
要允许用户通过HTML表单上传文件，最关键的一步是正确配置form标签的enctype属性。当表单包含文件输入字段时，必须将enctype设置为multipart/form-data。这指示浏览器以特殊方式编码表单数据，以便服务器能够正确解析文件内容。
以下是一个包含文件上传字段的HTML表单示例：
立即学习“前端免费学习笔记（深入）”；
<form action="/dish/new" method="POST" enctype="multipart/form-data">
<label for="name">菜品名称:</label>
<input type="text" name="name" id="name" required />
<br />
<label for="desc">描述:</label>
<textarea name="desc" id="desc"></textarea>
<br />
<label for="cost">价格:</label>
<input type="number" name="cost" id="cost" required />
<br />
<label for="isnonveg">是否非素:</label>
<input type="checkbox" name="isnonveg" id="isnonveg" />
<br />
<label for="image-input">选择图片:</label>
<input
type="file"
name="thumbnail"
id="image-input"
accept="image/png, image/jpg, image/jpeg"
hidden
/>
<button type="button" onclick="document.getElementById('image-input').click()">上传图片</button>
<br />
<button type="submit">提交</button>
</form>在这个示例中，input type="file"字段的name属性（例如thumbnail）将用于在后端识别上传的文件。accept属性限制了用户可以选择的文件类型。
2. 后端Express环境准备
在Node.js Express应用中处理multipart/form-data类型的请求，需要一个专门的中间件。express-fileupload是一个轻量级且功能强大的中间件，可以方便地处理文件上传。
2.1 安装 express-fileupload
首先，通过npm安装express-fileupload：
npm install express-fileupload
2.2 注册中间件
在您的Express应用主文件（通常是app.js或server.js）中，引入并注册express-fileupload中间件：
const express = require('express');
const fileUpload = require('express-fileupload');
const app = express();
// 其他中间件，例如body-parser（用于处理非文件字段）
app.use(express.json()); // 解析JSON格式的请求体
app.use(express.urlencoded({ extended: true })); // 解析URL-encoded格式的请求体
// 注册express-fileupload中间件
// 可以在此处添加配置选项，例如文件大小限制、临时目录等
app.use(fileUpload({
createParentPath: true, // 允许自动创建目标目录
limits: { fileSize: 5 * 1024 * 1024 }, // 限制文件大小为5MB
abortOnLimit: true // 达到限制时中止请求
}));
// 定义静态文件目录，以便浏览器可以访问上传的图片
app.use(express.static('public'));
// ... 其他路由和应用配置通过app.use(fileUpload())注册后，所有后续请求中上传的文件都将可以通过req.files对象访问。
3. 处理文件上传路由
现在，您可以在Express路由中处理上传的文件了。express-fileupload会将上传的文件信息添加到req.files对象中。每个文件都会成为req.files的一个属性，属性名对应于HTML表单中input type="file"字段的name属性。
例如，如果您的文件输入字段的name是thumbnail，那么在后端您可以通过req.files.thumbnail访问该文件。
const express = require('express');
const router = express.Router();
const path = require('path'); // 用于处理文件路径
router.post('/dish/new', async (req, res) => {
try {
// 获取非文件字段数据
let { name, desc, cost, isnonveg } = req.body;
// 检查是否有文件上传
if (!req.files || Object.keys(req.files).length === 0) {
return res.status(400).send('没有文件被上传。');
}
// 获取上传的文件，这里假设文件输入字段的name是'thumbnail'
let thumbnail = req.files.thumbnail;
// 验证文件类型（可选但推荐）
const allowedTypes = ['image/png', 'image/jpg', 'image/jpeg'];
if (!allowedTypes.includes(thumbnail.mimetype)) {
return res.status(400).send('只允许上传PNG、JPG或JPEG格式的图片。');
}
// 生成一个唯一的文件名，以避免文件冲突
// 推荐使用UUID或时间戳结合原始文件名
const fileName = `${Date.now()}-${thumbnail.name}`;
const uploadPath = path.join(__dirname, '../public/images/dishes', fileName);
// 使用mv()方法将文件移动到目标目录
await thumbnail.mv(uploadPath);
console.log(`图片已存储到: ${uploadPath}`);
// 在这里可以进行数据库操作，将文件路径存储到数据库中
// 例如：await Dish.create({ name, desc, cost, isnonveg, thumbnailPath: `/images/dishes/${fileName}` });
res.redirect('/success'); // 上传成功后重定向
} catch (err) {
console.error('文件上传失败:', err);
res.status(500).send('文件上传失败，请稍后再试。');
}
});
module.exports = router;代码解释：
- req.files.thumbnail: 这是express-fileupload中间件解析后，代表上传文件的对象。它包含文件的各种属性，如name（原始文件名）、mimetype（文件类型）、size（文件大小）以及最重要的mv()方法。
- thumbnail.mv(uploadPath, callback): 这是express-fileupload提供的一个便捷方法，用于将文件从临时目录移动到指定的uploadPath。它是一个异步操作，可以返回一个Promise，因此可以使用await来等待其完成。
- path.join(__dirname, '../public/images/dishes', fileName): 使用Node.js内置的path模块来构建跨平台兼容的文件路径。__dirname表示当前文件所在的目录。../public/images/dishes是相对于当前文件（例如路由文件）的上传目标目录。
- 错误处理: try...catch块用于捕获文件移动过程中可能发生的错误，并向用户返回适当的响应。
4. 完整示例与注意事项
为了使整个文件上传流程更加健壮和安全，还需要考虑以下几点：
4.1 目录结构
建议将上传的文件存储在项目根目录下的一个公共可访问的目录中（例如public/uploads或public/images），并配置Express的静态文件服务，以便前端可以访问这些文件。
// app.js 或 server.js app.use(express.static(path.join(__dirname, 'public')));
4.2 文件命名
为了避免文件覆盖和提高安全性，强烈建议不要直接使用用户上传的原始文件名。应该为上传的文件生成一个唯一的文件名，例如结合时间戳、UUID或哈希值。
const { v4: uuidv4 } = require('uuid'); // 安装 npm install uuid
const fileName = `${uuidv4()}-${thumbnail.name.replace(/\s/g, '_')}`; // 替换空格以避免URL问题4.3 文件类型和大小验证
在服务器端进行文件类型和大小验证至关重要，以防止恶意文件上传或服务器资源耗尽。express-fileupload可以在初始化时设置limits和abortOnLimit，但更精细的类型验证应在路由处理函数中进行，检查file.mimetype。
4.4 目录创建
确保目标上传目录存在。express-fileupload的createParentPath: true选项可以自动创建不存在的父目录，这在开发阶段非常方便。但在生产环境中，您可能希望有更严格的目录管理策略。
4.5 异步操作
文件I/O操作是异步的。确保您的代码正确处理Promise或回调，以避免竞态条件或数据不一致。async/await是处理此类异步操作的推荐方式。
总结
通过本教程，您应该已经掌握了在Node.js Express应用中实现文件上传的核心技术。关键步骤包括：
- 前端HTML表单：设置enctype="multipart/form-data"。
- 后端Express：安装并注册express-fileupload中间件。
- 路由处理：通过req.files访问上传的文件，并使用file.mv()方法将文件移动到服务器的本地目录。
此外，为了构建一个生产就绪的文件上传功能，务必考虑文件命名策略、文件类型/大小验证、错误处理以及目标目录管理等最佳实践。
