React / 系统课时
上传文件资源
上传文件资源
文件上传不只是读取一个 File:接口还要限制类型和大小、生成安全文件名,并把内容交给可靠的存储。本节用 Route Handler 接收 multipart/form-data,完成基础校验和本地写入,再说明生产环境的存储边界。
学习目标
- 使用
request.formData()从 Route Handler 读取上传文件 - 对文件类型、空文件和大小做服务端校验
- 生成服务端文件名并完成写入与结果验证
从表单读取 File
Route Handler 可以直接调用 request.formData() 读取表单数据,不需要 Pages Router 时代的 bodyParser 配置。表单字段可能是字符串,也可能是 File,所以取得 file 后必须先判断类型。:contentReference[oaicite:1]{index=1}
上传处理可以拆成接收、校验、命名、存储四步。任何一步失败都应立即返回明确状态码,避免把不合格文件写入磁盘或对象存储。

实现类型、大小与存储处理
下面示例允许 PNG、JPEG 和 PDF,最大 2 MiB。示例把文件写入项目根目录的 uploads,适合本地开发或明确拥有持久磁盘的自托管 Node.js 环境。
import { randomUUID } from 'node:crypto'
import { mkdir, writeFile } from 'node:fs/promises'
import path from 'node:path'
export const runtime = 'nodejs'
const MAX_FILE_SIZE = 2 * 1024 * 1024
const ALLOWED_TYPES = new Map([
['image/png', '.png'],
['image/jpeg', '.jpg'],
['application/pdf', '.pdf'],
])
export async function POST(request: Request) {
const formData = await request.formData()
const value = formData.get('file')
if (!(value instanceof File)) {
return Response.json({ error: 'File is required' }, { status: 400 })
}
const extension = ALLOWED_TYPES.get(value.type)
if (!extension) {
return Response.json({ error: 'Unsupported file type' }, { status: 415 })
}
if (value.size === 0 || value.size > MAX_FILE_SIZE) {
return Response.json({ error: 'Invalid file size' }, { status: 413 })
}
// 不直接使用客户端文件名,避免路径字符、重名和可预测名称带来的风险。
const filename = `${randomUUID()}${extension}`
const uploadDir = path.join(process.cwd(), 'uploads')
const bytes = Buffer.from(await value.arrayBuffer())
await mkdir(uploadDir, { recursive: true })
await writeFile(path.join(uploadDir, filename), bytes)
return Response.json(
{ name: filename, size: value.size, type: value.type },
{ status: 201 },
)
}预期结果:
合法 PNG/JPEG/PDF 且不超过 2 MiB:写入 uploads 目录并返回 201
缺少 file:返回 400
类型不在白名单:返回 415
空文件或超过 2 MiB:返回 413这里的 MIME 类型来自客户端声明,只适合作为第一层过滤。面对不可信上传,还应根据文件签名检查真实格式,并按业务需要增加恶意内容扫描、访问权限和生命周期策略。
发送文件并检查结果
将代码保存为 app/api/uploads/route.ts,启动开发服务器后,用一个实际存在的 PNG 文件验证接口:
curl -i -F "file=@avatar.png;type=image/png" \\
http://localhost:3000/api/uploads预期输出:
HTTP/1.1 201 Created
content-type: application/json
{"name":"<ID>.png","size":<VALUE>,"type":"image/png"}<ID> 是服务端生成的随机标识,<VALUE> 是实际字节数。随后检查项目根目录的 uploads,应出现与响应中 name 一致的文件;上传超过 2 MiB 的文件应得到 413,上传未允许的类型应得到 415。
生产环境不要依赖应用本地磁盘
许多 Serverless 部署环境的应用文件系统并不是持久存储,实例重建后本地文件可能消失,因此不能把上述目录当作生产资源库。生产环境通常应把校验后的字节写入 S3、R2、Blob Storage 等对象存储,数据库只保存对象键、URL 或业务元数据。
如果文件较大,进一步应考虑客户端直传对象存储并使用短期签名 URL,避免文件内容完整经过应用服务器。无论采用哪种存储方式,服务端都必须继续校验“谁能上传、允许什么类型、最大多大以及最终归谁”。