中文文件名乱码是因为HTTP协议要求Content-Disposition的filename参数仅支持ASCII字符，直接传入UTF-8中文会导致浏览器解析不一致；必须手动构造符合RFC 5987标准的filename*=utf-8''{encoded}格式头，使用url.PathEscape编码并避免混用c.FileAttachment()。
c.FileAttachment() 本身不处理中文文件名编码，直接传入会导致浏览器解析失败或显示为问号、下划线或乱码。必须手动构造符合 RFC 5987 的 Content-Disposition 头。
为什么中文文件名会乱码
HTTP 协议规定 Content-Disposition 中的 filename 参数只允许 ASCII 字符；中文属于 UTF-8 多字节字符，未经编码直接塞进去，不同浏览器行为不一致：Chrome 可能显示为 %E6%B5%8B%E8%AF%95.xlsx，Safari 直接截断，IE/Edge 完全忽略。Gin 的 c.FileAttachment("路径", "中文名.xlsx") 内部只是简单拼接 filename=，没做 RFC 5987 编码。
正确设置 Content-Disposition 头（RFC 5987）
要用 filename*=utf-8''{encoded} 格式，其中 {encoded} 是 url.PathEscape() 或 url.QueryEscape() 编码后的结果。注意：url.PathEscape() 更适合文件名（保留斜杠含义），url.QueryEscape() 会把空格转成 +，不太适合下载场景。
-
url.PathEscape("测试报告.xlsx")→%E6%B5%8B%E8%AF%95%E6%8A%A5%E5%91%8A.xlsx -
url.QueryEscape("测试报告.xlsx")→%E6%B5%8B%E8%AF%95%E6%8A%A5%E5%91%8A.xlsx（效果相同，但语义略偏查询参数） - 必须用单引号分隔：
filename*=utf-8''%E6%B5%8B%E8%AF%95.xlsx，不能写成filename*=utf-8"%E6%B5%8B..."
示例：
func DownloadWithCNName(c *gin.Context) {
filePath := "./downloads/测试报告.xlsx"
c.Header("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
c.Header("Content-Disposition", "attachment; filename*=utf-8''"+url.PathEscape("测试报告.xlsx"))
c.File(filePath)
}
避免 c.FileAttachment() 的隐式 filename 覆盖
调用 c.FileAttachment(filePath, "中文名.xlsx") 会自动设置 Content-Disposition: attachment; filename="中文名.xlsx" —— 这个原始值没有编码，会覆盖你手动设的 filename*=。所以：不要混用。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- ✅ 正确：手动设头 +
c.File() - ❌ 错误：
c.FileAttachment()+ 后续再c.Header("Content-Disposition", ...)（后者被前者忽略） - ⚠️ 注意：
c.File()不设任何 Content-Disposition，默认是inline；必须自己加头才能触发下载
Windows 系统下额外兼容性处理
部分旧版 IE 和 Edge（非 Chromium 内核）对 filename*= 支持不完整，可添加 fallback：filename="fallback.xls" 作为降级。浏览器按顺序解析，支持 RFC 5987 的优先用 filename*=，否则退到 ASCII 名。
示例：
c.Header("Content-Disposition",
"attachment; filename=\"fallback.xls\"; filename*=utf-8''"+url.PathEscape("销售报表2024.xlsx"))
注意双引号包裹 ASCII fallback，单引号包裹 encoded 部分，中间用分号隔开。
实际部署时最容易被忽略的是：开发环境路径能跑通，但上线后工作目录变了，filePath 拼错导致 c.File() 返回 404，而乱码问题反而被掩盖。先确保文件存在且路径可读，再调中文名逻辑。 
