gPdf
使用场景 · 物流与发货

承运商级规模的物流面单 PDF

渲染 4×6 英寸热敏物流面单，内含矢量 GS1-128 条码、ITF-14 箱码和 SSCC-18 托盘 ID。Edge 渲染让 Black Friday 峰值下的 p99 仍低于 15 ms。

要解决的问题

直接从订单 JSON 渲染可进入承运商流程的 4×6 英寸热敏物流面单，包括矢量 GS1-128、ITF-14 和 SSCC-18 条码；每个请求不需要启动一个无头浏览器。输出必须能在 Zebra、SATO、Honeywell 打印机上以 203 dpi 可靠扫码，并在零售峰值期间保持 p99 低于 15 ms。

为什么用 gPdf

  • 矢量 Code 128、QR、DataMatrix、PDF417 以及 GS1-128 / ITF-14 / SSCC-18，在 203 dpi、300 dpi 和 600 dpi 下都具备亚像素级精度。
  • 0.1 mm 坐标精度，满足承运商对人可读解释行整体长度的公差要求。
  • 页面尺寸 `label_4_6_in`（以及 `label_4_8_in`、`label_a6`）已预配置为主流热敏打印格式。
  • 确定性输出：同一份订单 JSON 渲染为字节一致的 PDF，仓库重打不会产生“另一张”标签。
  • Edge 渲染：承运商提货时同一分钟打印 5 万张面单，仍可保持 p50 3 ms、p99 8 ms。
  • 无状态：面单在 Cloudflare Worker isolate 的内存中存在约 4 ms，随后释放。没有文档存储，也不会形成承运商数据泄露面。

示例请求

POST /api/v1/pdf/render - 带 Code 128 承运商追踪条码的最小 4×6 英寸热敏面单。

{
  "pages": [{
    "size": "label_4_6_in",
    "elements": [
      {
        "type": "text",
        "x": 4, "y": 6,
        "content": "SHIP TO",
        "style": { "font_size": 8, "font_family": "NotoSans-Regular" }
      },
      {
        "type": "text",
        "x": 4, "y": 12,
        "content": "Acme Distribution Centre\n1200 Logistics Pkwy\nMemphis TN 38116",
        "style": { "font_size": 11, "font_family": "NotoSans-Regular" }
      },
      {
        "type": "barcode",
        "format": "code128",
        "content": "1Z999AA10123456784",
        "x": 4, "y": 60,
        "width": 92, "height": 22,
        "barcode_text": { "enabled": true, "position": "bottom" }
      }
    ]
  }]
}

合规与验证

  • GS1 General Specifications：模块宽度（X-dimension）、静区和整体长度在 203 dpi 下符合 GS1 第 5.4 节公差。
  • 承运商要求：UPS、FedEx、DHL 和 USPS 可将渲染输出识别为可扫描面单；无需按承运商再做后处理。
  • 如需因税务或审计原因留存面单 PDF，可通过 `settings.profile = "pdfa-2b"` 使用 PDF/A-2b 归档输出。

用一句话理解物流面单工作负载

每个订单生成一份 PDF，每份 PDF 在热敏打印机上打印一次；如果系统变慢，失败模式不是“页面加载慢”，而是“仓库提货口被你的面单渲染 API 堵住”。物流面单是一个 p99 延迟就是核心产品指标的场景；重打很常见，所以确定性输出很重要；条码质量也不是看像素，而是看 GS1 X-dimension 公差能否让扫描枪第一次就读出来。

基于无头浏览器的 PDF 栈很难同时满足这三点：峰值下冷启动成本会叠加，小尺寸热敏标签上的栅格条码会退化，字体栅格化还会随 Chromium 版本漂移，因此“字节一致的重打”基本不可实现。

为什么 gPdf 适合

一张 4×6 英寸热敏面单很小（203 dpi 下为 576 × 864 像素）、元素数量少（文本块、1-2 个条码、可选承运商 Logo），但量很大（中型 3PL 每天渲染 5 万到 50 万张）。这正是 gPdf 面向的工作负载。渲染器会：

  1. 一次性解析版式：页面坐标、字体级联和条码几何在请求时解析，不依赖浏览器 layout engine。
  2. 将每个条码矢量化：模块直接绘制进 PDF 流，让 30 mm 宽的 GS1-128 在 203 dpi 或 600 dpi 下都能清晰读取，调用方不需要自行处理 DPI 感知的栅格化逻辑。
  3. 嵌入 NotoSans CJK + Latin：同一份数据里的中文承运商名称也能正确渲染，不需要你在渲染容器里额外准备字体。

在我们的参考工作负载中（EU-WEST 上对上方样例执行 1,000 次调用），p99 稳定在 8 ms。单个 isolate 是刚渲染 1 张面单，还是已经渲染 1 万张面单，结果都一样。

量级与成本计算

一个典型中型 3PL 大约每天处理 5 万张面单，也就是每月约 150 万页。按 Basic 套餐（5 美元/月含 10 万页，超出部分每页 0.00005 美元） 计算：

150 万页 × 0.00005 美元 = 75.00 美元超额费用
+ Basic 套餐基础费用       =  5.00 美元
─────────────────────────────────────
合计                       = 80.00 美元/月

同样的工作负载如果放在 Puppeteer-on-Lambda 上，以常见 Lambda 并发配置计算，通常会落在 200-400 美元/月 区间；这还没计入高峰期的冷启动成本。

Black Friday 示例

峰值冲击最能体现 Edge 渲染的价值。假设一个零售客户在 Black Friday 第一小时达到平时 200% 的面单量：60 分钟内生成 10 万张面单，平均每分钟 1,700 张，峰值突发达到每分钟 5,000 张。这个工作负载可以在单个 Cloudflare Workers 区域池内完成，没有冷启动税。

同样的工作负载如果跑在按平均流量配置的 Puppeteer 预热池上，突发扩容出来的容器会产生 1.5-2.5 秒冷启动，仓库提货台会切实感受到每一次延迟。

下一步

延伸阅读