文件上传、下载与静态资源访问

保存受限大小的上传文件,通过 ID 下载,并公开指定静态文件

🎯 引言

学完这篇文章,你能接收表单中的文件、返回下载地址,并为公开文件配置静态访问。

📤 用 Multer 接收上传文件

浏览器用 FormData 上传文件时,请求类型为 multipart/form-data。Express 项目通常使用 Multer 解析其中的文件和字段,上传结果放在 req.file。

安装本节需要的依赖:

npm install multer@2.5.0

新建 files-app.mjs,准备上传目录:

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:

files-app.mjs
const upload = multer({
    dest: uploadDir,
    limits: { fileSize: 1024 * 1024, files: 1, fields: 0 }
});

dest 指定保存目录,Multer 为文件生成保存名。fileSize 限制每个文件为 1 MiB,files 限制一个文件,fields: 0 表示这个接口不接收额外文本字段。

磁盘保存避免把整个文件长期留在内存里。大小超限由 Multer 报错,后面将它转换为 413。


📥 在路由中取得文件信息

添加上传接口:

files-app.mjs
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 下载

添加下载接口:

files-app.mjs
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。添加静态目录:

files-app.mjs
const publicDir = fileURLToPath(new URL('./public/', import.meta.url));
app.use('/static', express.static(publicDir, { dotfiles: 'deny' }));

访问 /static/readme.txt 就能读到文本。该目录内的文件对访问者公开,因此不要把私有上传、.env 或源码放入其中;上传目录与静态目录保持分开。


🧯 处理上传和下载失败

把错误中间件放在路由后:

files-app.mjs
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,交给框架结束连接。


🧪 上传后实际下载

新建启动文件:

files-server.mjs
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。

// 请在这里记录结果