gin 本身不支持 pdf 生成，动态分块导出需在路由中生成 html 或用 gofpdf/chromedp 渲染；c.file() 仅适用于静态文件，无法满足变量填充、分页等动态需求；分块逻辑必须由业务代码明确划定。
Gin 框架本身不内置 PDF 生成能力，所谓“动态分块导出 PDF”，本质是：在 Gin 路由中按需生成 HTML 内容（含分页逻辑），再调用外部库（如 gofpdf、unidoc 或 headless Chrome）渲染为 PDF。关键不在 Gin，而在如何把「动态内容」合理切分成 PDF 的“块”（如每页一个报告节、每 N 条记录一页），并控制布局。
为什么不能直接用 c.File() 实现动态 PDF 导出
c.File() 只能发送已存在的静态文件，无法响应请求时实时拼装数据、渲染模板、分页或插入图表。一旦你有变量填充、条件段落、表格跨页、页眉页脚等需求，就必须走「生成 → 写入内存/临时文件 → 返回响应」路径。
- 常见错误现象：
http: superfluous response.WriteHeader call，源于先调用c.Header()又误用c.File()或c.String() - 典型场景：巡检报告导出（见 Gin-Vue-Admin 示例）、合同批量生成、带签名区域的表单 PDF
- 性能影响：每次请求都触发完整 HTML 渲染 + PDF 转换，CPU 和内存开销明显；建议对高频导出加缓存或异步队列
用 gofpdf 手动分块：适合结构简单、字段可控的场景
gofpdf 是纯 Go 实现、无外部依赖的 PDF 库，适合服务端轻量导出。它的“分块”靠手动控制 SetY() 和 AddPage() 实现，不自动处理文本换行或表格跨页。
- 必须预估每块高度：比如标题占 10pt、每条记录占 6pt，算出一页最多放 25 条，超出就
pdf.AddPage() - 避免中文乱码：需显式注册中文字体，例如
pdf.AddUTF8Font("simhei", "", "fonts/simhei.ttf") - 示例关键片段：
pdf := gofpdf.New("P", "pt", "A4", "") pdf.AddUTF8Font("simhei", "", "fonts/simhei.ttf") pdf.AddPage() pdf.SetFont("simhei", "", 14) pdf.CellFormat(0, 20, "巡检报告 - "+time.Now().Format("2006-01-02"), "", 0, "C", false, 0, "") // 每 25 条后换页 for i, item := range data { if i%25 == 0 && i > 0 { pdf.AddPage() } pdf.SetX(50) pdf.CellFormat(0, 12, fmt.Sprintf("%d. %s", i+1, item.Name), "", 0, "L", false, 0, "") }
用 HTML + chromedp 渲染：适合复杂样式、分页 CSS、图表嵌入
这是目前最接近“前端所见即 PDF”的方案：用 Gin 渲染一个带 @media print 和 page-break-inside: avoid 的 HTML 页面，再通过 chromedp 启动 headless Chrome 截图成 PDF。分块逻辑全由 CSS 控制，更可靠。
- 容易踩的坑：
chromedp需要系统安装 Chrome 或指定--headless=new兼容路径；容器部署时易因缺少字体或沙箱权限失败 - 关键 CSS 分页控制：
<style> @media print { .section { page-break-inside: avoid; } .page-break { page-break-before: always; } } </style> - Gin 中返回 HTML 前需确保路径可访问（如静态资源用
r.Static()挂载），否则 Chrome 加载失败 - 性能提示：首次调用
chromedp启动慢，建议复用chromedp.ExecAllocator实例，避免每次新建浏览器
PDF 分块导出中最容易被忽略的点
不是“怎么生成”，而是“谁来负责分页语义”。Gin 只管 HTTP 层，gofpdf 不懂业务逻辑，chromedp 不解析数据结构——真正决定“一块是什么”的，是你传给模板或 PDF 构造函数的数据切片逻辑。比如巡检任务结果导出，必须在调用 PDF 生成前就按 job.ID 和 cluster 分组，而不是指望 PDF 库自动聚类。这个分块边界，必须由业务代码明确划定。
