根本原因是多个goroutine共用同一个pdf.Document实例,而gofpdf不支持并发写入;正确做法是每个goroutine独立创建gofpdf.New实例,避免共享和加锁,并通过限流channel控制并发数防止OOM。

goroutine并发生成PDF时,为什么PDF内容会错乱或丢失?
根本原因是多个goroutine共用了同一个pdf.Document实例(比如用gofpdf.New创建后反复调用AddPage、Cell等),而gofpdf不支持并发写入。实际运行时可能 panic 报 concurrent map iteration and map write,或生成的PDF打开失败/内容重叠/页码错乱。
正确做法是:每个goroutine独立创建自己的pdf.Fpdf对象,各自生成完整PDF文件(或字节流),再统一收集。不要试图“共享一个PDF对象+加锁”。
- 每个PDF任务必须调用一次
gofpdf.New(或gofpdf.NewCustom)初始化新实例 - 避免在goroutine外提前声明
pdf := gofpdf.New(...)然后传入闭包 - 如果需复用字体、模板等,可封装成函数参数传入,而非复用pdf实例
如何安全地并发生成N份PDF并保存到磁盘?
关键在于隔离IO操作和错误处理——每个goroutine负责自己的文件写入,主goroutine只做协调和结果收集。不要让多个goroutine争抢同一个os.File或共用os.WriteFile路径。
示例结构:
立即学习“go语言免费学习笔记(深入)”;
var wg sync.WaitGroup
var mu sync.Mutex
var errors []error
<p>for i, data := range reportData {
wg.Add(1)
go func(idx int, d Report) {
defer wg.Done()
// ✅ 每个goroutine新建PDF
pdf := gofpdf.New("P", "mm", "A4", "")
pdf.AddPage()
pdf.SetFont("Arial", "", 12)
pdf.Cell(40, 10, fmt.Sprintf("Report #%d", idx))</p><pre class="brush:php;toolbar:false;"> // ✅ 写入独立文件(带唯一名称)
filename := fmt.Sprintf("report_%d.pdf", idx)
err := pdf.OutputFileAndClose(filename)
if err != nil {
mu.Lock()
errors = append(errors, fmt.Errorf("report %d: %w", idx, err))
mu.Unlock()
}
}(i, data)} wg.Wait()
- 务必用
defer wg.Done()确保计数器准确,否则wg.Wait()可能永远阻塞 - 文件名必须唯一(如含序号、UUID),否则并发写入会覆盖
- 若需返回PDF字节流而非存盘,用
pdf.OutputBytes(),别用OutputFileAndClose
内存爆炸?批量生成PDF时如何控制goroutine数量
直接对几百个报表启动几百个goroutine,极易OOM——每个gofpdf.Fpdf实例至少占用几MB内存,PDF内容越复杂(图片、字体嵌入)越明显。Go runtime不会自动限流,必须手动节制。
推荐用带缓冲的channel做信号量:
sem := make(chan struct{}, 10) // 最多10个并发
for i, data := range reportData {
sem <- struct{}{} // 获取令牌
go func(idx int, d Report) {
defer func() { <-sem }() // 归还令牌
pdf := gofpdf.New("P", "mm", "A4", "")
// ... 生成逻辑
pdf.OutputFileAndClose(fmt.Sprintf("report_%d.pdf", idx))
}(i, data)
}- 缓冲大小建议设为CPU核心数的1.5~2倍(如8核设12),而非盲目设大
- 避免用
runtime.NumCPU()直接当并发数——PDF生成是IO+CPU混合型,不是纯计算 - 如果PDF含大量图片,还需考虑系统文件描述符限制,
ulimit -n可能需调高
生成PDF后合并成单个文件?别在goroutine里做
合并PDF(如用unidoc或pdfcpu)是重量级操作,本身不支持并发安全合并。若在每个goroutine末尾调用合并,会导致文件被反复读写、竞态甚至损坏。
正确顺序是:先并发生成所有独立PDF → 主goroutine等待全部完成 → 单独一步合并。
- 生成阶段只输出
report_001.pdf、report_002.pdf等临时文件 - 合并逻辑放在
wg.Wait()之后,用pdfcpu merge命令或unidoc/pdf/creator库顺序加载 - 注意合并库的内存占用——合并100个1MB PDF可能瞬时吃掉2GB内存,需监控
真正麻烦的从来不是“怎么起goroutine”,而是PDF库的线程安全性、内存生命周期和文件IO边界是否划清。漏掉任意一环,表面跑通,线上压测就崩。



















