上传接口需区分FormValue和FormFile：文本字段用FormValue获取，文件字段用FormFile获取；前端必须用FormData构造请求并设置Content-Type: multipart/form-data；Bind不处理文件，需手动分开绑定；大文件上传须初始化时设置e.MaxMultipartMemory。
上传接口必须区分 FormValue 和 FormFile
表单混合提交（如文本字段 + 文件）时，FormValue 拿不到文件字段的值，FormFile 也拿不到普通文本字段——这是初学者最常卡住的地方。Echo 不会自动把所有字段“合并”进一个 map，它严格按 HTTP 协议解析：文件走 multipart 的 file part，文本走 value part。
常见错误现象：c.FormValue("filename") 返回空字符串，但用 c.FormFile("filename") 却报 no multipart content ——说明请求根本没带 Content-Type: multipart/form-data，或者前端没用 FormData 构造请求。
- 确保前端用
FormData.append("name", "xxx")和FormData.append("avatar", fileInput.files[0])同时提交 - 后端先调
c.FormFile("avatar")获取文件句柄，再调c.FormValue("title")获取描述文字 - 不要对文件字段尝试
Bind结构体，Bind默认不处理文件，会静默跳过
Bind 能不能自动绑定上传字段？不能，但可以手动补全
Bind 方法只处理请求体中的结构化数据（JSON/XML/form-urlencoded），它不触碰 multipart 中的文件部分。如果你坚持用结构体接收上传参数，得自己拼接：
比如有结构体：
type UploadReq struct {
Title string `form:"title"`
Tag string `form:"tag"`
}
你仍需分开处理：
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 用
c.Bind(&req)绑定title和tag - 再用
c.FormFile("avatar")单独取文件 - 如果结构体里硬塞了个
*multipart.FileHeader字段，Bind不识别，会忽略——别这么干
大文件上传必须提前配置 MaxMultipartMemory
默认 Echo 只允许 32MB 内存缓冲区处理 multipart，超过就直接报错 http: request body too large，而不是流式写入磁盘。这个限制不是靠中间件控制，而是在初始化 Echo 实例时硬编码的。
正确做法是初始化时显式设置：
e := echo.New() e.MaxMultipartMemory = 64 << 20 // 64MB
- 数值单位是字节，建议用位移写法避免手误（
64 比 <code>67108864清晰） - 设太大可能引发 OOM，设太小会导致大文件上传直接失败，没有重试机会
- 这个值不影响
FormFile返回的*multipart.FileHeader，但影响后续file.Open()是否能成功读取内容
文件名乱码、中文路径失败？检查 Content-Disposition 编码
浏览器上传中文文件名时，不同内核对 Content-Disposition 的编码方式不一致（RFC 5987 vs RFC 2231），导致 FileHeader.Filename 解析失败或出现 .jpg。
目前没有通用解码方案，务实做法是：
- 服务端不依赖原始文件名做存储，用 UUID 重命名
- 若必须保留原名，优先从
FileHeader.Header.Get("Content-Disposition")手动提取并尝试多种解码（url.PathUnescape+charset.Lookup("gbk").NewDecoder().Bytes()） - 前端传文件前，用
encodeURIComponent处理文件名字段（仅当自定义上传逻辑时可行）
真正容易被忽略的是：这个乱码问题在本地开发（Chrome）可能正常，一上生产（Safari 或某些企业微信内置浏览器）就崩——务必用真机或对应 UA 复现测试。
