我之前在做iOS上用HTML模板生成PDF的时候也踩过分页的坑，给你梳理几个实用的排查方向和修复建议，应该能帮你解决问题：

• 检查@media print中分页属性的正确用法
  iOS底层用的WebKit内核对分页属性的兼容性有一些细节要注意：

  • 优先用现代标准属性break-after: page搭配旧属性page-break-after: always做兼容，避免只写其中一个。
  • 别给浮动元素设分页属性，WebKit对浮动元素的分页支持很差，尽量把需要分页的区域改成块级元素，用clear: both清除浮动，或者直接用Flex布局替代浮动。
  • 避免给带overflow: hidden的容器加分页规则，这会直接阻止分页触发；同时检查父容器有没有设置page-break-inside: avoid，不然会覆盖你的分页指令。
    给你一个靠谱的示例代码：

  @media print {
    .page-break {
      page-break-after: always;
      break-after: page;
      clear: both;
      margin: 0;
      padding: 0;
    }
    /* 防止内容被拆分到两页的通用类 */
    .no-split {
      page-break-inside: avoid;
      break-inside: avoid;
    }
  }
  

• 排查HTML内容里的隐性干扰项
  300行的HTML很容易藏着影响分页的细节：

  • 检查长文本块、图片、表格有没有加page-break-inside: avoid？比如大表格如果没设这个，可能会把分页符挤到页面末尾。
  • 别给父容器设固定height！如果内容溢出固定高度的容器，WebKit可能不会触发分页，尽量用min-height或者让容器随内容自然撑开。
  • 图片要加max-width: 100%; height: auto;，如果图片宽度超出打印页面，会撑破布局导致分页逻辑混乱。

• 检查Swift PrintRenderer的配置细节
  你的自定义PrintRenderer或者系统UIPrintPageRenderer的设置也可能影响分页：

  • 确保paperRect和printableRect的尺寸符合你的PDF规格（比如A4的点尺寸是595.2 x 841.8），边距设置不合理会导致内容计算错误，分页位置偏移。
  • 如果用WKWebView加载HTML，一定要等页面完全渲染完成再生成PDF！可以在webView(_:didFinish:)回调里触发PDF生成，避免因为内容未加载完导致分页异常。
    给你一个参考的渲染代码片段：

  func generatePDF(from webView: WKWebView, completion: @escaping (Data?) -> Void) {
      let renderer = UIPrintPageRenderer()
      let formatter = webView.viewPrintFormatter()
      renderer.addPrintFormatter(formatter, startingAtPageAt: 0)
      
      // 设置A4页面尺寸与边距
      let a4Size = CGSize(width: 595.2, height: 841.8)
      renderer.setValue(a4Size, forKey: "paperSize")
      let printableArea = CGRect(x: 20, y: 20, width: a4Size.width - 40, height: a4Size.height - 40)
      renderer.setValue(printableArea, forKey: "printableRect")
      
      // 生成PDF数据
      let pdfData = NSMutableData()
      UIGraphicsBeginPDFContextToData(pdfData, printableArea, nil)
      for pageIndex in 0..<renderer.numberOfPages {
          UIGraphicsBeginPDFPage()
          renderer.drawPage(at: pageIndex, in: UIGraphicsGetPDFContextBounds())
      }
      UIGraphicsEndPDFContext()
      completion(pdfData as Data)
  }
  

• 用最小复现案例定位问题
  如果上面的排查都没解决，建议先把HTML简化到只有核心内容和分页规则，测试是否能正常分页。如果简化后没问题，再逐步加回原来的内容，就能找到导致分页异常的具体元素或样式了。

内容的提问来源于stack exchange，提问作者CountCiano