file

来自 <input type="file"> 或 FormData 的文件：大小和类型。

签名

function file(options?: { maxSize?: number; types?: string[] }, msg?: Message): Schema<File>

参数

参数	类型	说明
options.maxSize	number	最大字节数：2 * 1024 * 1024
options.types	string[]	MIME 类型、类型组和扩展名：['image/*', 'application/pdf', '.docx']
msg	Message	文件所有错误的自定义信息

错误代码

代码	触发条件	默认信息
required	值为空且该字段为必填	Required
file	不是文件	Must be a file
fileSize	文件大于 maxSize	File must be at most {max}
fileType	类型不在列表中	File type must be one of: {types}

可以修改这些文本：见 错误信息与国际化。

注意事项

• 可在浏览器和 Node 20+ 中使用 —— 在 Node 中 File 来自 FormData（fetch、Hono、Nuxt 中的 request.formData()）。
• 信息中的 {max} 是易读的大小：2 MB。错误的 params 中还有 size —— 文件大小。
• 扩展名不区分大小写：.pdf 也接受 DOC.PDF。
• 多个文件 —— 使用 array 配合 maxLength。

示例

头像

const avatar = file({ maxSize: 2 * 1024 * 1024, types: ['image/*'] });

多个文档

const Application = object({
  documents: pipe(array(file({ types: ['application/pdf', '.docx'] })), minLength(1), maxLength(5)),
});

在服务端

app.post('/upload', async (c) => {
  const form = Object.fromEntries(await c.req.formData());
  const { avatar } = parse(object({ avatar: file({ maxSize: 2 * 1024 * 1024 }) }), form);
});

另请参阅

• array
• maxLength