直接用gin.context.writer写excel文件会乱码或下载失败，因为.xlsx是二进制格式，而gin默认按utf-8文本处理响应；必须设置正确content-type和content-disposition头，禁用c.string()/c.json()等覆盖writer的方法，并使用excelize.writeto()或bytes.buffer流式输出。
为什么直接用 gin.Context.Writer 写 Excel 文件会乱码或下载失败
因为 Excel 文件（.xlsx）是二进制格式，而 Gin 默认把响应当作 UTF-8 文本处理。如果直接用 c.String() 或未设置正确 Header 就写入字节，浏览器会尝试解析成文本，导致乱码、文件损坏或无法打开。
- 必须显式设置
Content-Type为application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - 必须设置
Content-DispositionHeader 指定附件名和编码，否则中文文件名在 Chrome/Firefox 下可能变成download.xlsx - 避免调用
c.JSON()、c.String()等会覆盖 Writer 的方法——生成完 Excel 后只用c.Data()或直接写Writer
用 github.com/xuri/excelize/v2 生成 Excel 并响应给前端
这是目前 Go 生态最稳定、支持 xlsx 且无需 Office 依赖的库。它不依赖 Cgo，适合容器部署，也支持样式、公式、多 Sheet。
- 生成文件后不要保存到磁盘——用
buf := &bytes.Buffer{}+f.Write(buf)直接写入内存缓冲区 - 响应时用
c.Data(200, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", buf.Bytes()) - 注意：如果用了
f.NewSheet()或f.SetCellValue()后没调用f.DeleteSheet("Sheet1")，默认的空白 Sheet1 会残留，影响用户观感
func exportExcel(c *gin.Context) {
f := excelize.NewFile()
// 删除默认 Sheet
index := f.GetSheetIndex("Sheet1")
f.DeleteSheet("Sheet1")
// 新建带名称的 Sheet
f.NewSheet("用户报表")
// 写表头
f.SetCellValue("用户报表", "A1", "ID")
f.SetCellValue("用户报表", "B1", "姓名")
f.SetCellValue("用户报表", "C1", "注册时间")
// 写数据（示例）
f.SetCellValue("用户报表", "A2", 1001)
f.SetCellValue("用户报表", "B2", "张三")
f.SetCellValue("用户报表", "C2", "2024-06-01")
// 输出到 buffer
buf := &bytes.Buffer{}
if err := f.Write(buf); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
c.Header("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
c.Header("Content-Disposition", `attachment; filename="user_report.xlsx"`)
c.Data(200, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", buf.Bytes())
}
中文文件名在不同浏览器下的兼容写法
单纯写 filename="用户报表.xlsx" 在 Safari 和旧版 Edge 里会出错；用 filename*=UTF-8''... 格式才真正跨浏览器兼容。
- 推荐组合写法：
c.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"; filename*=UTF-8''%s`, "user_report.xlsx", url.PathEscape("用户报表.xlsx"))) - 注意：
url.PathEscape是必须的，它把中文转成%E7%94%A8%E6%88%B7%E6%8A%A5%E8%A1%A8.xlsx，符合 RFC 5987 - 不要用
filename*=UTF-8''用户报表.xlsx这种裸字符串——URL 编码缺失会导致 Safari 拒绝解析
大报表导出时内存和超时问题怎么绕开
Excelize 把整个工作簿构建在内存里，导出 10 万行以上容易 OOM 或触发 Gin 默认 30s 超时。不能靠调大 ReadTimeout 解决根本问题。
- 对大数据量，改用流式写法：用
f.AddSheet()后配合f.SetRow()分批写入，避免一次性缓存所有单元格 - 更稳妥的做法是异步导出——入库任务记录，用 goroutine 生成文件存到对象存储（如 MinIO），再返回下载链接
- 务必在 handler 开头加
c.Writer.Flush()配合io.Pipe实现边生成边传输（但 Excelize 不原生支持流式写入，需自行封装或换库如tealeg/xlsx，不过后者已归档不维护）
实际项目中，超过 2 万行就该切异步。同步导出的“快”是假象，卡住的是整个 HTTP 连接和 Goroutine，不是用户感知的下载速度。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
