Iris框架不内置上传组件,但提供ctx.FormFile和ctx.UploadFormFiles等原生API实现单/多文件上传,需手动处理路径、校验、大小限制及临时文件清理。

Iris 框架本身不内置“上传组件”,但提供了极简、可控的原生文件处理能力。批量上传、文件夹上传、大小限制、路径控制等,全靠你调用 ctx.FormFile 或 ctx.UploadFormFiles 配合标准 Go 文件操作完成——没有魔法,只有明确的控制权。
单文件上传:用 ctx.FormFile 而不是自己解析 multipart
别手动调 r.ParseMultipartForm,Iris 的 ctx.FormFile 已封装好校验和读取逻辑,且自动应用 SetMaxRequestBodySize 限制。
-
ctx.FormFile("file")返回*multipart.FileHeader,含原始文件名、大小、MIME 类型 - 必须提前设置最大请求体:用
ctx.SetMaxRequestBodySize(10 * iris.MB)或全局配置iris.WithPostMaxMemory(10 * iris.MB) - 文件名不安全:
fileHeader.Filename可能含../或空格,务必用path.Base()截取纯文件名 - 保存时路径要存在:目标目录(如
"./uploads")需手动创建,否则os.OpenFile会报No such file or directory
示例关键片段:
app.Post("/upload", func(ctx iris.Context) {
ctx.SetMaxRequestBodySize(10 * iris.MB)
file, fileHeader, err := ctx.FormFile("file")
if err != nil {
ctx.StopWithError(iris.StatusBadRequest, err)
return
}
defer file.Close()
<pre class="brush:php;toolbar:false;">dest := filepath.Join("./uploads", path.Base(fileHeader.Filename))
if err := ctx.SaveFormFile(file, dest); err != nil {
ctx.StopWithError(iris.StatusInternalServerError, err)
return
}
ctx.Writef("Uploaded: %s", path.Base(fileHeader.Filename))
})
多文件上传:用 ctx.UploadFormFiles 处理数组式表单字段
前端必须用 ,后端才能用 ctx.UploadFormFiles 批量接收。注意字段名末尾的 [] 是硬性约定,不是可选。
-
ctx.UploadFormFiles("./uploads")自动遍历所有同名upload[]字段,返回成功上传的文件列表和总字节数 - 它内部已做文件名校验和路径清理,但不会覆盖同名文件——若
./uploads/logo.png已存在,第二次上传会失败并返回 error - 如需避免冲突,得自己在保存前加时间戳或 UUID 前缀:
uuid.New().String() + "-" + path.Base(fileHeader.Filename) - 不要用
MultipartFile[]这类 Spring 风格参数;Iris 不走反射绑定,只认ctx.FormFile和ctx.UploadFormFiles
curl 测试命令(注意字段名带 []):
curl -X POST http://localhost:8080/upload \ -F "upload[]=@/tmp/a.jpg" \ -F "upload[]=@/tmp/b.pdf"
文件夹上传:浏览器支持有限,webkitdirectory 不是标准属性
目前仅 Chromium 内核(Chrome/Edge)支持 input[webkitdirectory],Firefox 和 Safari 完全不识别。Iris 后端无法“感知”文件夹结构——它收到的仍是扁平的文件列表,只是前端把路径信息藏在了 file.webkitRelativePath 中。
- 前端需启用:
- 后端拿到
fileHeader后,读fileHeader.Header.Get("X-File-Relative-Path")或尝试解析fileHeader.Filename(部分浏览器会带斜杠路径) - 更可靠的做法:前端 zip 打包后上传,后端用
archive/zip解压并按内部路径重建目录树 - Iris 不提供解压能力,也不建议在 HTTP 请求中直接处理嵌套目录——这属于业务逻辑层该做的事,不是框架职责
常见错误与绕过点
很多问题其实和 Iris 无关,而是 multipart 协议、Go 标准库或部署环境导致的。
-
http: request body too large:没调ctx.SetMaxRequestBodySize,或 Nginx 的client_max_body_size比 Iris 限制更小,两者必须一致 -
no multipart boundary:前端没设Content-Type: multipart/form-data,或用了axios.post但没传FormData对象(自动设 header),而是传了 JSON -
open ./uploads/xxx: permission denied:Linux 下运行 Iris 的用户对./uploads目录无写权限,别用root启动,改用chown或chmod -
context canceled:上传超时,需检查ctx.SetMaxRequestBodySize是否过小,以及是否遗漏ctx.ReadTimeout/ctx.WriteTimeout配置
真正容易被忽略的是:Iris 的文件上传不自动清理临时文件。如果你用 ctx.FormFile 读取后没显式 defer file.Close(),或大文件上传中途断开,临时 multipart 缓存可能堆积在系统临时目录里——这点必须靠运维监控或定期清理脚本兜底。











