Iris 文件上传常因四点失败:multipart 未解析、临时目录权限不足、大小限制未配置、ctx.FormFile() 返回 nil 却不报错;根本原因是 Iris 默认不自动解析 multipart,需显式调用 ParseMultipartForm 或 ReadForm。

直接说结论:Iris 的文件上传接口本身不难,但容易卡在 multipart 解析失败、临时目录权限、大小限制未显式配置、以及 ctx.FormFile() 返回 nil 却没报错这四个点上。
为什么 ctx.FormFile("file") 总是返回 nil?
这不是代码写错了,而是请求根本没被正确识别为 multipart。Iris 默认不会自动解析 multipart 表单——它把解析权交给你,避免无意义的内存开销。
必须在 handler 前显式调用 ctx.Request().ParseMultipartForm(),或更稳妥地用 ctx.FormFile() 前加一次 ctx.ReadForm(32 (32MB 上限):
app.Post("/upload", func(ctx iris.Context) {
// 必须先读取表单,否则 FormFile() 永远 nil
if err := ctx.ReadForm(32 << 20); err != nil {
ctx.StatusCode(400)
ctx.WriteString("form parse failed: " + err.Error())
return
}
<pre class="brush:php;toolbar:false;">file, info, err := ctx.FormFile("file")
if err != nil {
ctx.StatusCode(400)
ctx.WriteString("no 'file' field or parse error")
return
}
defer file.Close()
dst, err := os.Create("./uploads/" + info.Filename)
if err != nil {
ctx.StatusCode(500)
ctx.WriteString("save failed")
return
}
defer dst.Close()
io.Copy(dst, file)})
- 不调
ReadForm()或ParseMultipartForm()→FormFile()返回nil, nil, nil,没有错误提示 -
ReadForm(n)中的n是最大内存缓存(单位字节),超出会写入临时磁盘;设太小会导致大文件直接失败 - 前端
<input type="file" name="file">的name必须和FormFile("xxx")里的字符串完全一致,区分大小写
如何支持多文件上传和自定义字段?
Iris 把 ctx.FormValue("xxx") 和 ctx.FormFile("xxx") 分开设计,是为了明确区分文本字段和文件字段——不能混用,也不能靠 ctx.PostValue() 读文件名。
多文件只需循环调用 FormFile,但注意:HTML 多选需加 multiple,且后端要遍历所有同名字段:
<input type="file" name="files" multiple>
后端处理:
if err := ctx.ReadForm(32 << 20); err != nil { /* ... */ }
<p>// 获取全部同名文件
files, err := ctx.MultipartForm()
if err != nil { /<em> ... </em>/ }</p><p>for _, f := range files.File["files"] {
file, err := f.Open()
if err != nil { continue }
defer file.Close()</p><pre class="brush:php;toolbar:false;">dst, _ := os.Create("./uploads/" + f.Filename)
io.Copy(dst, file)}
-
ctx.MultipartForm()返回完整*multipart.Form,.File是map[string][]*multipart.FileHeader -
.Value字段才是普通文本,比如ctx.MultipartForm().Value["user_id"] - 不要试图用
ctx.FormValue("files")读文件名——它永远为空
上传路径、权限与临时文件清理
Iris 不接管临时文件生命周期,FormFile() 返回的 *os.File 是内存或临时磁盘上的句柄,关掉就丢;你负责保存、重命名、清理。
常见坑:
-
os.Create()写入路径不存在 → 报no such file or directory,需提前os.MkdirAll("./uploads", 0755) - Linux 下运行用户(如
www-data)对./uploads无写权限 → 静默失败或 panic - 没调
defer file.Close()→ 文件句柄泄漏,上传几次后系统报too many open files - 没检查
info.Size→ 用户传个 2GB 压缩包,服务 OOM
建议在 ReadForm() 前加尺寸校验:
// 先读 header,检查 Content-Length
if ctx.Request().ContentLength > 100<<20 { // 100MB
ctx.StatusCode(413)
ctx.WriteString("file too large")
return
}
为什么本地测试能传,上线 Nginx 就 413?
不是 Iris 的问题,是反向代理截断了。Nginx 默认 client_max_body_size 是 1MB,超过直接 413,请求根本到不了 Go 进程。
必须在 Nginx 配置里显式放大:
location /upload {
client_max_body_size 100M;
proxy_pass http://localhost:8080;
}
- 这个值必须 ≥ Iris 里
ReadForm()的参数,且 ≥ 前端预估最大文件 - 如果用 Caddy,对应配置是
body_limit 100MB - Cloudflare 等 CDN 层也有上传限制,需单独确认
真正麻烦的从来不是框架 API,而是 multipart 请求穿过层层中间件时,每一层都可能悄悄吞掉你的文件——从 Nginx 到 Go runtime 再到业务逻辑,漏掉任意一环的尺寸声明或解析调用,都会让 FormFile() 返回空,还不告诉你为什么。


















