直接往c.Writer写PDF易出错，因未设Content-Type和Content-Disposition响应头，导致浏览器误渲染或下载损坏；且未调用c.Abort()可能引发重复写响应错误。
为什么直接用 gin.Context.Writer 写 PDF 容易出错
直接往 c.Writer 写入 PDF 二进制数据，但没设响应头或没调用 c.Abort()，浏览器大概率会把 PDF 当 HTML 渲染成乱码，或者触发下载但文件损坏。根本原因是 Gin 默认 Content-Type 是 text/plain; charset=utf-8，而 PDF 必须是 application/pdf，且需明确告知浏览器“这是附件”。
- 漏设
c.Header("Content-Type", "application/pdf")→ 浏览器无法识别格式 - 漏设
c.Header("Content-Disposition", "attachment; filename=report.pdf")→ 可能内联打开而非下载，或文件名乱码 - 生成 PDF 失败后仍继续执行后续 handler → 可能重复写响应，触发
http: multiple response.WriteHeader calls错误 - PDF 字节流写入前未清空 Writer 缓冲（如用了
c.Data()则不用管，但手写io.Copy时容易忽略）
用 gofpdf 生成 PDF 并通过 Gin 下载的最小可行写法
gofpdf 是 Go 里最轻量、无需外部依赖的 PDF 生成库，适合服务端简单报表。关键不是“怎么画 PDF”，而是“怎么不卡住 Gin 的响应流程”。
示例：生成一页带标题的 PDF 并下载
func downloadPDF(c *gin.Context) {
pdf := gofpdf.New("P", "mm", "A4", "")
pdf.AddPage()
pdf.SetFont("Arial", "B", 16)
pdf.Cell(40, 10, "Hello from Gin!")
<pre class="brush:php;toolbar:false;">// 生成字节流
buf := new(bytes.Buffer)
if err := pdf.Output(buf); err != nil {
c.JSON(500, gin.H{"error": "PDF generation failed"})
return
}
// 正确设置响应头并输出
c.Header("Content-Type", "application/pdf")
c.Header("Content-Disposition", "attachment; filename=hello.pdf")
c.Data(200, "application/pdf", buf.Bytes())}
立即学习“go语言免费学习笔记（深入）”；
-
c.Data()自动处理写入和状态码，比手动c.Writer.Write()更安全 - 务必在
c.Data()前设好Content-Disposition，否则 Safari 可能拒绝下载 - 中文支持需额外加载字体（
pdf.AddUTF8Font()），否则显示方块 —— 这不是 Gin 问题，是gofpdf限制 - 若 PDF 较大（>10MB），考虑用
c.Stream()避免内存积压，但必须确保流不中断
用 gotenberg 替代纯 Go 生成 PDF 的真实场景判断
当需要渲染 HTML 模板（含 CSS/图表/复杂排版）为 PDF 时，硬用 gofpdf 会陷入样式调试地狱。这时候该上 gotenberg——它是个独立 HTTP 服务，接收 HTML，返回 PDF。
- 部署
gotenberg容器：docker run --rm -p 3000:3000 thecodingmachine/gotenberg:7 - Gin 中发起请求：
http.Post("http://localhost:3000/convert/html", "application/json", bytes.NewReader(payload)) - payload 是 JSON，含
html字段（可含内联 CSS）和marginTop等打印参数 - 优势：完美支持 Flex/Grid/字体嵌入；劣势：多一跳网络调用，需运维额外服务
- 别在 Gin handler 里用
time.Sleep()等待 gotenberg —— 它本身有超时机制，应直接透传响应
下载接口被 Nginx 或反向代理截断的排查点
本地跑通，上线后 PDF 下载一半就停？大概率是反向代理（Nginx / ALB / Cloudflare）主动关闭了长连接或限制了响应体大小。
- Nginx 需显式配置：
proxy_buffering off;+proxy_max_temp_file_size 0;（避免缓存大 PDF 到磁盘） - 加
proxy_buffer_size 128k;和proxy_buffers 4 256k;防止缓冲区溢出 - Cloudflare 默认限制 100MB 响应体，若 PDF 超限会返回
521 Origin Down，需升级计划或改用直连 - 确认 Gin 日志里没有
write tcp: broken pipe—— 这说明客户端（浏览器）已断开，但服务端还在写
生成 PDF 下载的本质不是“怎么画图”，而是“怎么让字节流干净、完整、按预期抵达浏览器”。中间任何一环（编码、头信息、代理、超时）断掉，用户看到的就是空白页或损坏文件。尤其注意 Content-Disposition 的双引号和 filename* 参数（兼容 UTF-8 文件名），这个细节线上出过太多次问题。
