文件上传、下载与静态资源访问
🎯 引言
学完这篇文章,你能接收表单中的文件、返回下载地址,并为公开文件配置静态访问。
📤 用 Multer 接收上传文件
浏览器用 FormData 上传文件时,请求类型为 multipart/form-data。Express 项目通常使用 Multer 解析其中的文件和字段,上传结果放在 req.file。
安装本节需要的依赖:
npm install multer@2.5.0
新建 files-app.mjs,准备上传目录:
import express from 'express';
import multer from 'multer';
import { fileURLToPath } from 'node:url';
export const app = express();
const uploadDir = fileURLToPath(new URL('./uploads/', import.meta.url));
目录固定在模块旁,不会随终端启动位置变化。上传目录单独保存,避免混入源码和配置文件。
📏 配置保存位置和大小上限
继续配置 Multer:
const upload = multer({
dest: uploadDir,
limits: { fileSize: 1024 * 1024, files: 1, fields: 0 }
});
dest 指定保存目录,Multer 为文件生成保存名。fileSize 限制每个文件为 1 MiB,files 限制一个文件,fields: 0 表示这个接口不接收额外文本字段。
磁盘保存避免把整个文件长期留在内存里。大小超限由 Multer 报错,后面将它转换为 413。
📥 在路由中取得文件信息
添加上传接口:
app.post('/files', upload.single('file'), (req, res) => {
if (!req.file) return res.status(400).json({ error: '请选择文件' });
res.status(201).json({
data: { id: req.file.filename, size: req.file.size }
});
});
single('file') 要求表单文件字段名为 file,解析后 req.file.filename 是服务器保存名,size 是字节数。返回 201 和这两个值,客户端使用 id 下载文件,不依赖用户提供的原文件名。
本例把文件作为附件保存,不执行上传内容。若功能要求只接收图片,还要验证实际文件格式、尺寸和内容,不能仅相信客户端的 MIME 类型声明。
📤 根据文件 ID 下载
添加下载接口:
app.get('/files/:id', (req, res, next) => {
if (!/^[a-f0-9]{32}$/.test(req.params.id)) {
return res.status(400).json({ error: '文件 ID 不合法' });
}
res.download(req.params.id, 'download.bin', { root: uploadDir }, error => {
if (error) next(error);
});
});
本版本 Multer 默认生成 32 位十六进制保存名。校验 id 后,res.download 只从 uploadDir 提供文件,并通过响应头建议浏览器下载;展示名使用固定的 download.bin。下载失败交给错误处理中间件。
私有文件必须先验证登录身份,再从数据库检查文件归属,之后才能下载。随机文件名不能代替权限检查。
🖼 用静态中间件公开指定目录
在示例目录创建 public/readme.txt,内容为 public demo。添加静态目录:
const publicDir = fileURLToPath(new URL('./public/', import.meta.url));
app.use('/static', express.static(publicDir, { dotfiles: 'deny' }));
访问 /static/readme.txt 就能读到文本。该目录内的文件对访问者公开,因此不要把私有上传、.env 或源码放入其中;上传目录与静态目录保持分开。
🧯 处理上传和下载失败
把错误中间件放在路由后:
app.use((error, req, res, next) => {
if (res.headersSent) return next(error);
if (error.code === 'LIMIT_FILE_SIZE') {
return res.status(413).json({ error: '文件超过 1 MiB' });
}
if (error instanceof multer.MulterError) return res.status(400).json({ error: '上传格式不符合要求' });
if (error.code === 'ENOENT') return res.status(404).json({ error: '文件不存在' });
console.error(error);
res.status(500).json({ error: '文件处理失败' });
});
错误字段名、多传文件等上传错误返回 400,超大文件返回 413,缺失文件返回 404。传输已开始时不能再发送 JSON,交给框架结束连接。
🧪 上传后实际下载
新建启动文件:
import { app } from './files-app.mjs';
app.listen(3000, '127.0.0.1');
运行 node files-server.mjs,准备一份小型 note.txt,发送:
curl -i http://127.0.0.1:3000/files -F 'file=@note.txt'
-F 发送表单文件,Multer 字段名同样为 file。得到 201 后,使用响应中的 id 下载:
curl http://127.0.0.1:3000/files/替换为实际id -o downloaded.txt
下载内容应与原文件一致。浏览器使用 FormData 时也添加 file 字段,并让浏览器自动设置包含分隔信息的 Content-Type,不手工固定这个头。
❓ 知识问答
Q1:express.json 能解析文件表单吗?
不能,它处理 JSON;multipart 文件表单由 Multer 处理。
Q2:限制单个文件大小就够了吗?
还要限制上传频率、用户总配额,并清理废弃文件,避免磁盘被大量小文件占满。
Q3:为什么不用上传文件名直接作为保存路径?
它由客户端提供,可能重名或包含路径信息。服务端生成保存名,原名只作为校验后的展示信息。
🧪 小练习
上传两个同名文件,确认保存 ID 不同;上传超过 1 MiB 的文件,确认得到 413。
// 请在这里记录结果
