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}

上传处理可以拆成接收、校验、命名、存储四步。任何一步失败都应立即返回明确状态码,避免把不合格文件写入磁盘或对象存储。

Next.js 文件上传处理链路

实现类型、大小与存储处理

下面示例允许 PNG、JPEG 和 PDF,最大 2 MiB。示例把文件写入项目根目录的 uploads,适合本地开发或明确拥有持久磁盘的自托管 Node.js 环境。

ts
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 },
  )
}

预期结果:

text
合法 PNG/JPEG/PDF 且不超过 2 MiB:写入 uploads 目录并返回 201
缺少 file:返回 400
类型不在白名单:返回 415
空文件或超过 2 MiB:返回 413

这里的 MIME 类型来自客户端声明,只适合作为第一层过滤。面对不可信上传,还应根据文件签名检查真实格式,并按业务需要增加恶意内容扫描、访问权限和生命周期策略。

发送文件并检查结果

将代码保存为 app/api/uploads/route.ts,启动开发服务器后,用一个实际存在的 PNG 文件验证接口:

bash
curl -i -F "file=@avatar.png;type=image/png" \\
  http://localhost:3000/api/uploads

预期输出:

text
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,避免文件内容完整经过应用服务器。无论采用哪种存储方式,服务端都必须继续校验“谁能上传、允许什么类型、最大多大以及最终归谁”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

上传文件资源

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通