16.02-文件类型校验

Content-Disposition: form-data; name="file"; filename="photo.png"
Content-Type: image/png

pnpm add file-type

import { fileTypeFromBuffer } from 'file-type'
 
const buffer = new Uint8Array([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])
const result = await fileTypeFromBuffer(buffer)
// { ext: 'png', mime: 'image/png' }

const file = body.get('file') as File
// 只读前 4100 字节，覆盖绝大多数格式的魔数位置
const slice = file.slice(0, 4100)
const buffer = new Uint8Array(await slice.arrayBuffer())
const detected = await fileTypeFromBuffer(buffer)

// 头像上传——只要 PNG 和 JPEG
const avatarAllowed = {
  extensions: ['png', 'jpg', 'jpeg'],
  mimeTypes: ['image/png', 'image/jpeg'],
}
 
// AI 知识库场景——接受 PDF 和 DOCX
const documentAllowed = {
  extensions: ['pdf', 'docx'],
  mimeTypes: [
    'application/pdf',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
  ],
}

import { fileTypeFromBuffer } from 'file-type'
import type { Context, MiddlewareHandler } from 'hono'
 
type FileValidationConfig = {
  /** 表单里文件字段的名称 */
  fieldName: string
  /** 允许的扩展名列表 */
  allowedExtensions: string[]
  /** 允许的 MIME 类型列表 */
  allowedMimeTypes: string[]
  /** 文件大小上限（字节） */
  maxFileSize: number
}
 
export function validateFileType(
  config: FileValidationConfig
): MiddlewareHandler {
  return async (c, next) => {
    let body: Record<string, FormDataEntryValue>
 
    try {
      body = await c.req.parseBody()
    } catch {
      return c.json(
        { error: 'INVALID_FORM_DATA', message: '请求体不是合法的 multipart 表单' },
        400
      )
    }
 
    const file = body[config.fieldName]
 
    // 字段不存在或不是文件
    if (!(file instanceof File)) {
      return c.json(
        { error: 'FILE_MISSING', message: `缺少文件字段：${config.fieldName}` },
        400
      )
    }
 
    // 文件大小检查
    if (file.size > config.maxFileSize) {
      return c.json(
        {
          error: 'FILE_TOO_LARGE',
          message: `文件大小超过限制（最大 ${config.maxFileSize} 字节）`,
        },
        413
      )
    }
 
    // 读取文件头部，检测真实类型
    const slice = file.slice(0, 4100)
    const buffer = new Uint8Array(await slice.arrayBuffer())
    const detected = await fileTypeFromBuffer(buffer)
 
    if (!detected) {
      return c.json(
        { error: 'UNKNOWN_FILE_TYPE', message: '无法识别文件类型' },
        400
      )
    }
 
    // 白名单校验：扩展名和 MIME 类型都要命中
    const extValid = config.allowedExtensions.includes(detected.ext)
    const mimeValid = config.allowedMimeTypes.includes(detected.mime)
 
    if (!extValid || !mimeValid) {
      return c.json(
        {
          error: 'FILE_TYPE_NOT_ALLOWED',
          message: `不支持的文件类型：${detected.mime}`,
          allowed: config.allowedMimeTypes,
        },
        415
      )
    }
 
    // 校验通过，把文件信息挂到 context，后续处理函数可以直接取
    c.set('validatedFile', {
      file,
      detectedType: detected,
    })
 
    await next()
  }
}

type AppEnv = {
  Bindings: { /* ... */ }
  Variables: {
    validatedFile?: {
      file: File
      detectedType: { ext: string; mime: string }
    }
  }
}

const upload = new Hono<AppEnv>()
 
upload.post(
  '/avatar',
  validateFileType({
    fieldName: 'file',
    allowedExtensions: ['png', 'jpg', 'jpeg'],
    allowedMimeTypes: ['image/png', 'image/jpeg'],
    maxFileSize: 5 * 1024 * 1024, // 5MB
  }),
  async (c) => {
    const { file, detectedType } = c.get('validatedFile')!
 
    // 文件已经通过类型校验，可以安全地进行后续处理
    // 比如存到 R2、调用图片压缩服务等
 
    return c.json({
      message: '上传成功',
      type: detectedType.mime,
      size: file.size,
    })
  }
)

// 文档问答接口——只接受文档类格式
const docQnAAllowed = {
  allowedExtensions: ['pdf', 'docx', 'txt', 'md'],
  allowedMimeTypes: [
    'application/pdf',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'text/plain',
    'text/markdown',
  ],
}
 
// 语音转文字接口——只接受音频格式
const speechToTextAllowed = {
  allowedExtensions: ['mp3', 'wav', 'webm', 'm4a'],
  allowedMimeTypes: [
    'audio/mpeg',
    'audio/wav',
    'audio/webm',
    'audio/mp4',
    'audio/x-m4a',
  ],
}

const TEXT_EXTENSIONS = new Set(['txt', 'md', 'csv'])
 
// 在中间件的校验逻辑里加一个分支
if (!detected) {
  // 没有检测到魔数，尝试按扩展名判断是否为纯文本
  const fileName = (file as File).name ?? ''
  const ext = fileName.split('.').pop()?.toLowerCase() ?? ''
 
  if (TEXT_EXTENSIONS.has(ext) && config.allowedExtensions.includes(ext)) {
    // 白名单里有这个扩展名，且属于纯文本类型，放行
    c.set('validatedFile', {
      file,
      detectedType: { ext, mime: `text/${ext === 'md' ? 'markdown' : 'plain'}` },
    })
    return next()
  }
 
  return c.json(
    { error: 'UNKNOWN_FILE_TYPE', message: '无法识别文件类型' },
    400
  )
}

// 根据功能场景设置不同的上限
const limits = {
  documentQA: 20 * 1024 * 1024,     // 文档问答：20MB
  speechToText: 25 * 1024 * 1024,    // 语音转文字：25MB（Whisper 上限）
  avatar: 5 * 1024 * 1024,           // 头像：5MB
  imageGeneration: 10 * 1024 * 1024, // 图片生成：10MB
}

{
  "error": "FILE_TYPE_NOT_ALLOWED",
  "message": "不支持的文件类型：application/x-executable",
  "allowed": ["image/png", "image/jpeg"]
}

type FileUploadError = {
  error: string
  message: string
  allowed?: string[]
  maxSize?: number
}
 
function fileUploadError(
  c: Context,
  code: string,
  message: string,
  status: number,
  extra?: Record<string, unknown>
) {
  return c.json(
    { error: code, message, ...extra },
    status
  )
}