最常见 panic 是 invalid memory address or nil pointer dereference，因未调用 c.request().parsemultipartform 就直接访问 c.formfile 或 c.multipartform；echo 不自动解析 multipart 数据，须先设内存限制再显式调用 parsemultipartform。
上传文件时 ParseMultipartForm 报错：invalid memory address or nil pointer dereference
这是最常遇到的 panic，根本原因是没调用 c.Request().ParseMultipartForm 就直接访问 c.FormFile 或 c.MultipartForm。Echo 不会自动解析 multipart 数据，必须显式调用。
正确做法是先设置内存限制再解析：
// 必须在读取文件前调用 err := c.Request().ParseMultipartForm(32
-
ParseMultipartForm的参数是最大内存缓存大小（单位字节），超过该值的文件部分会暂存到磁盘临时文件 - 传
0会导致内部使用默认 32MB，但不建议依赖默认值，显式声明更可控 - 如果请求不是
multipart/form-data类型，ParseMultipartForm会返回http.ErrNotMultipart，需单独判断
c.FormFile 返回 nil, nil 或 no such file 错误
这通常不是代码 bug，而是前端没按规范提交：字段名不匹配、enctype 缺失、或用了 fetch 但没构造 FormData 对象。
检查点：
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 确认 HTML 表单有
enctype="multipart/form-data"，且<input type="file">的name和后端c.FormFile("xxx")中的字符串一致 - 若用 JS 提交，确保用
new FormData(formElement)或手动 append，不能直接JSON.stringify -
c.FormFile在无对应字段时返回nil, nil（不是 error），需用== nil判断，而非检查 error - 上传空文件（用户点了选择但没选中任何文件）也会返回
nil, nil，业务上要区分“未上传”和“上传了空文件”
大文件上传中途断开，服务端收不到完整数据
默认情况下，Echo 本身不处理连接中断，但底层 net/http 的 ReadTimeout 和反向代理（如 Nginx）的超时配置会截断请求。
关键控制点：
- 启动 Echo 时设置
HTTPServer.ReadTimeout（例如 300 秒），避免小文件也因默认 30 秒超时失败 - 如果前面有 Nginx，必须同步调整
client_max_body_size、client_body_timeout和proxy_read_timeout -
ParseMultipartForm的内存限制只影响缓冲策略，不影响总上传时间；真正卡住往往是网络层或代理层超时 - 上传完成前服务端崩溃或重启，临时文件可能残留，建议用
os.TempDir()外的自定义临时路径，并配定期清理
保存文件时出现 permission denied 或 no space left on device
错误来自 file.Open 或 dst.Write，和 Echo 无关，但容易误以为是框架问题。
实操建议：
- 目标目录需对运行 Echo 进程的用户（如
www-data）有写权限，用ls -ld /path/to/upload确认 - 不要硬编码绝对路径，用
filepath.Join(uploadDir, filename)拼接，并提前os.MkdirAll(uploadDir, 0755) - 从
c.FormFile获取的*multipart.FileHeader里Size是客户端声明的大小，不可信；应边读边写并统计实际接收字节数，防止恶意声明超大Content-Length - 磁盘空间不足时，
io.Copy可能只写入部分数据就返回no space left on device，需检查返回的written值是否等于源文件大小
ParseMultipartForm 是否成功就直接调 FormFile」，以及「把 Nginx 超时当成 Go 代码问题来调试」。
