Iris框架本身不生成PDF,需结合gofpdf/unidoc等库生成,并通过设置Content-Type和inline头实现浏览器预览,前端用pdf.js可靠渲染。

Iris 框架本身不生成 PDF,也不处理在线预览 —— 它只是 Go 语言的 HTTP 路由框架,PDF 生成和渲染必须靠外部库 + 前端配合完成。
用 gofpdf 或 unidoc 在 Iris 中生成 PDF 文件
Go 生态里没有“开箱即用”的 PDF 渲染引擎,Iris 作为轻量路由层,只负责把请求转给生成逻辑。常见选择有:
-
gofpdf:纯 Go 实现,无依赖,适合简单报表(如单页订单、证书),但不支持复杂样式、字体嵌入需手动处理; -
unidoc(github.com/unidoc/unipdf/v3):功能完整(模板、水印、表单、加密),但商用需授权,免费版有页数/功能限制; - 绕过 Go 直接调用系统命令(如
weasyprint或wkhtmltopdf):需服务器装对应二进制,启动时检查exec.LookPath("wkhtmltopdf"),失败直接 panic。
关键点:Iris 的 ctx.Response().Writer() 必须设对 header,否则浏览器会下载而非预览:
ctx.ResponseWriter().Header().Set("Content-Type", "application/pdf")
ctx.ResponseWriter().Header().Set("Content-Disposition", "inline; filename=report.pdf")
漏掉 inline 就默认触发下载,这是最常踩的坑。
前端用 pdf.js 实现真正可靠的在线预览
Iris 后端只需提供 PDF 文件的可访问 URL(比如 /api/pdf/report/123),预览完全交给前端 pdf.js。别用 —— 浏览器内置 PDF 查看器行为不一致(Safari 不支持缩放、Edge 可能崩溃、移动端白屏)。
最小可行集成步骤:
- 从 CDN 引入:
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.4.120/pdf.min.js"></script>; - HTML 容器:
; - JS 加载逻辑中必须显式设置 workerSrc(新版 pdf.js 强制要求):
pdfjsLib.GlobalWorkerOptions.workerSrc = "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.4.120/pdf.worker.min.js";; - 加载失败时,
PDFDocumentLoadingTask的catch会抛出网络错误或 PDF 格式错误(如后端返回 500 但 content-type 是 pdf),务必捕获并提示用户。
Iris 静态文件服务要显式允许 .pdf MIME 类型
如果你把生成的 PDF 存在磁盘并用 iris.StaticWeb("/pdfs", "./data/pdfs") 暴露,IIS 或 Nginx 可能没问题,但 Iris 内置静态服务默认不识别 .pdf,会导致响应头缺失 Content-Type,前端拿到乱码。
解决方法只有两个:
- 手动注册 MIME:
iris.RegisterView(iris.HTML("./views", ".html").Binary(iris.Binary{Ext: ".pdf", ContentType: "application/pdf"}))—— 但这是 view 层,不适用于纯文件; - 更稳妥的是改用
ctx.ServeFile(filepath, false)并在之前手动写 header:ctx.ContentType("application/pdf"); - 或者干脆不用静态服务,统一走 API 路由(如
GET /api/pdf/:id),由 handler 控制读取、加日志、限流、鉴权。
真正难的不是“怎么拼出一个 PDF”,而是确保从 Go 写入磁盘的字节流、Iris 发出的 HTTP 头、pdf.js 解析器接收的响应三者严格一致 —— 任意一环多写一个 BOM、少一个 header、路径带空格未编码,都会导致预览失败且报错信息极其模糊。建议每次生成后用 curl -I 检查响应头,再用 file report.pdf 确认文件实际格式。











