跳转到正文
@krstation/xlsx2pdf-pro

在 Excel 里设计模板
一键生成高保真 PDF

模板标记替换 → HTML → PDF 的 Node.js 生成库。社区版开源免费(Apache-2.0),Excel 排版、样式、合并格与页面设置全保留,图片 / 条码 / 二维码富媒体标记与明细行内置;Pro 商业版叠加精确列宽、单页自适应、水印与图片压缩、批量出单与生产护栏,内置无头 Chrome 保证像素级渲染一致。

$npm ixlsx2pdf社区版 · 开源免费
版本对比免费 POC
Excel 模板通过浏览器渲染,生成带图片、条码、二维码与印章的 PDF 文件

把 Excel 报表,变成系统里的 PDF,卡在哪

报告单、票据、标签等固定模板要搬进后端批量生成 PDF,往往在渲染一致性、复杂元素拼接、国产打印链路与并发稳定性上翻车。

渲染一致性难保证

手写 HTML 模板与 Excel 设计对不齐,换浏览器 / 换 PDF 引擎样式就走样,反复调 CSS 仍难像素级还原。

国产打印链路方向错

Chromium 不写 /Rotate,WPS 打印预览 / Clodop 读不到方向标志,横向纸表现为「内容横向、纸张纵向」。

图片 / 条码拼接繁琐

报告要嵌照片、条码、二维码、印章,手动定位与压缩易错、难维护,层级堆叠更是无从下手。

并发渲染内存爆掉

每个渲染标签页 +100MB 起步,无节制并发把宿主机 / 容器直接打到 OOM,服务被单个异常请求击穿。

单元格定死大小、文本溢出跨页

Excel 单元格宽高在模板里就已定死,而实际文本长短千变万化;长内容装不下就撑破格子、被截断或挤到下一页,导致一份报告意外跨页、版式错乱。

自定义纸张识别不了

小票纸等自定义尺寸被静默当成 A4 生成,版式全乱;ExcelJS 又不解析文件内的 paperWidth/Height。

四大核心价值,
让 Excel 模板稳定出 PDF

从「像不像设计稿」「渲染准不准」「跑不跑得稳」「能不能扩展」四个维度,重构报表模板的 PDF 生成方式。点击卡片展开详情。

五大功能领域,
覆盖模板到产物全链路

围绕「模板标记 → 数据注入 → 渲染打印」核心链路,提供标记替换、数字格式、页面适配、多页批量与生成 API 五大能力。

四类内置标记两版通用,
一个模板搞定图文码

单元格写 ${字段|类型_参数} 即可,文本、图片、条形码、二维码四类内置标记两版通用(社区版 1.1.0 起内置富媒体),支持宽高 / 偏移 / 层级 / 透明度 / 默认值参数;水印为 Pro 专属。

文本水印(Pro)

作废 / 已审核叠章,宽度不足自动收敛换行,层级透明度可配

图片嵌入

base64 / URL / 本地路径;社区按原图尺寸归一,Pro DPI 物理尺寸 + 压缩

条码与二维码

barcode(code128) / qrcode,可配 zindex / opacity 堆叠

文本与富文本

text 默认类型,单元格内局部加粗 / 斜体 / 字色自动继承

一条从模板到 PDF 的生成链

从在 Excel 写标记到拿到 PDF Buffer,每一步都由引擎自动完成,调用方只管传模板和数据。点击节点查看详情。

当前节点 / 01

设计模板,把版式留在 Excel

在 Excel 中排版、设样式、合并单元格,需要动态填充的格写 ${字段|类型_参数} 标记,页面设置一并保存,模板即设计稿。

Excel 排版标记占位页面设置

样式保留

字色 / 背景 / 局部富文本格式照搬

标记占位

文本 / 图片 / 条码 / 二维码(水印 Pro)

页面设置

纸张 / 方向 / 页边距 / 缩放

让模板变更回到 Excel,减少前端拼接

通过标记替换、格式自动继承、内置无头 Chrome 与生产级护栏,把传统「手写 HTML → 拼元素 → 调样式 → 导 PDF」的长链路压缩为「设计模板 → 注入数据」的短链路。

流程对比

传统方式vsxlsx2pdf

从依赖前端手写模板到业务在 Excel 自助设计,让报表 PDF 生成更高效、更一致、更可控。

传统方式
1手写 HTML 模板›2拼图片 / 条码›3反复调 CSS 对齐›4换引擎样式走样›5手动导出 PDF
xlsx2pdf
1Excel 设计模板›2写 ${标记}›3注入数据›4内置 Chrome 打印›5一致 PDF 产出

标记替换

文本 / 图片 / 条码 / 二维码四类内置标记两版通用,水印 Pro

格式自动继承

百分比 / 货币 / 千分位 / 日期与 Excel 所见一致

无头 Chrome

像素级渲染一致,横向页自动补 /Rotate 标志

生产级护栏

Pro 并发限流 + 内存准入守卫;社区版固定上限 + 单并发

一套标记语法,
在单元格里描述一切

标记格式为 ${字段|类型_参数},竖杠及其后可省略(省略按文本处理)。字段支持 a.b、a.0.b 点路径取嵌套 / 数组值,#数组.字段 用于明细行逐行递增(两版内置);文本、图片、条形码、二维码四类内置标记共用同一套参数体系,水印为 Pro 专属类型。

${photo|image_w120_h40}
字段名(支持点路径 / #数组明细行)
标记类型(省略即 text)
参数键值(以 _ 连接)
text

文本替换

默认类型,可省略竖杠。局部富文本格式自动继承。

${name} / ${name|text}
image

图片嵌入

img 为别名;base64 / URL / 本地路径。社区按原图尺寸归一(@96DPI),Pro 按 DPI 物理尺寸 + 自动压缩。

${photo|image_w120_h40}
barcode

条形码

code128 编码,值为要编码的文本,缺省宽 100 高 20。

${code|barcode_w200_h60}
qrcode

二维码

值为要编码的文本,可配 zindex / opacity 与其他元素堆叠。

${qr|qrcode_w80_h80}
watermark

文本水印(Pro)

浮在单元格上的文本层,作废 / 已审核叠章,字号自适应;社区版自定义 handler 可返回水印浮层。

${mark|watermark_zindex1_opacity0.3}

参数键一览(以 _ 连接,可任意组合)

图片 / 条码 / 二维码 / watermark 共用同一套层级与透明度规则;minsize / lineheight 随 Pro 单页自适应与水印生效。

w / h

宽 / 高 px。缺省时社区按原图尺寸归一(@96DPI);Pro 按物理尺寸(像素÷DPI×96),只设一边另一边按宽高比。

ox / oy

水平 / 垂直偏移 px,oy 可为负,用于精细定位浮层元素。

zindex

层级:0 跟模板同层、负数在下方、正数在上方;设为非 0 后按纯浮层处理,不撑高所在行。

opacity

不透明度 0~1(同 CSS);值 >1 时按百分数自动换算,旧写法无需改动。

minsize

字号下限 pt:随 Pro 单页自适应生效,收敛后不低于该值;社区版不生效。

lineheight

watermark 专用(Pro):行高 pt,主要影响换行后的行间距,缺省按字体默认行高。

_默认: / _dft:

标记末尾追加,字段缺值时生效,如 ${remark|text_默认:无}。

#数组.字段

明细行语法,模板中逐行重复同一标记,每出现一次自动取数组下一项。

任意纸张,
从具名到自定义全覆盖

具名纸张两版直选;小票、标签等自定义纸张为 Pro 能力——优先从模板文件直读宽高,读不到再显式传参,绝不静默退成 A4。

A3A4A5B4B5letterlegal{ width, height } 自定义
01

具名纸张直选

option.pageSize 传 A3 / A4 / A5 / B4 / B5 / letter / legal 即按标准尺寸出纸,方向由 orientation 控制。

02

自定义纸张传参

传 { width, height }(单位 mm)即可出任意尺寸,小票、标签、异形版面不受具名纸张限制。

03

文件内宽高直读

第三方工具写入模板的 paperWidth / paperHeight 会绕过 ExcelJS 直接解包读取,无需显式传 pageSize。

04

单位自动换算

支持 mm / cm / in / pt / pi / pc,无单位按 mm 处理;landscape 时反交换回纵向基准,语义与传参一致。

05

读不到绝不静默

自定义 / 非标准代码读不到宽高时报错引导显式传参,绝不静默生成 A4;未写 paperSize 才按 Excel 内建默认兜底。

06

横向 /Rotate 标记(Pro)

横向页自动补写 Excel/WPS 式 /Rotate 90,WPS 打印预览与 Clodop 能正确选到横向纸,可关闭。

开箱即用,
落到任意 Node 环境

一条命令安装,内置无头 Chrome 自动就绪;ESM / CJS 双模式消费,浏览器策略灵活,容器与小内存场景有专门护栏。

01

一键安装

  • npm i xlsx2pdf
  • postinstall 自动下载内置 Chrome
  • 镜像源 + 重试 + Linux 依赖自动装
  • Node ≥ 18.17.0
02

跳过浏览器下载

  • .npmrc 写 browser=false
  • 环境变量 XLSX2PDF_SKIP_BROWSER=1
  • 一次性 --no-browser 标志
  • 不阻断安装,可后续补装
03

ESM / CJS 双模式

  • import 与 require 均可用
  • 附 TypeScript 类型声明
  • excel2pdf / excel2html 两个核心函数
  • 只要 HTML 时不启浏览器更轻量
04

浏览器策略

  • configure({ browserPath }) 外部浏览器
  • 环境变量 XLSX2PDF_BROWSER_PATH
  • 包内 browsers/ 内置 Chrome 兜底
  • ensureBrowser / closeBrowser 管控
05

Docker 部署

  • 基础镜像建议 node:18+
  • 自动装 Chrome 所需系统库
  • maxConcurrency 限流 + 内存准入守卫(Pro)
  • 单 worker 优先,避免多实例叠加

可扩展标记引擎,
把库变成你的报表中台

三层扩展点、两级注册(全局 use() / 调用级 option.plugins),自定义标记类型、字段解析器与模型后处理钩子,内部工具经 helpers 同源开放。

3层扩展点4+1类内置标记7+1个 helpers 工具2级插件注册

自定义标记类型,
一个 handler 就是一种元素

markerTypes 注册自定义类型,handler 签名 async (value, option, ctx)。取值链路已在 handler 之前自动完成,只管渲染;返回字符串 / images / watermarks,Pro 图片自动进入 sharp 压缩管线,社区按原图尺寸归一。

  • 取值已就绪 — fieldResolvers → 扁平取值 → 标记内默认值 → option.defaults 自动完成
  • 返回值契约 — string 文本 / { images } 图片 / { watermarks } 水印 / 混合 / null 清除
  • 异常不中断 — handler 抛错打印 <b>[engine]</b> 后按空值清除,其余标记照常
seal-plugin.js
import { use, helpers } from 'xlsx2pdf';

use({
  name: 'seal-plugin',
  markerTypes: {
    // 模板标记:stamp|seal_w100_h100
    seal: async (value, option) => {
      if (!value) return null;              // 空值清除标记
      const buf = await helpers.getFileBuffer(value);
      return {
        images: [{
          dataUrl: helpers.bufferToDataUrl(buf, 'png'),
          width: option.width || 100,
          height: option.height || 100,
        }],
      };                                    // Pro 自动走 sharp 压缩管线;社区按原图尺寸归一
    },
  },
});

图片自动压缩(Pro)

handler 返回 images 自动进入 sharp 压缩管线(缩至显示尺寸 + JPEG 转换);社区版纯 JS 按原图尺寸归一,不压缩。

异常不中断

handler 抛异常不会中断生成,控制台打印 [engine] 错误后该标记按空值清除,其余照常。

numFmt 可复用

自定义 handler 可通过 ctx.numFmt 读单元格格式、用 helpers.formatValue 复用同一格式化实现。

图片缓存复用

ctx.imageCache 按「类型|宽|高|值」缓存,自定义图片类 handler 可复用它避免重复下载 / 编码。

调用级隔离

option.plugins 仅本次生成生效、同名覆盖全局,避免多租户并发下的插件污染。

稳定扩展契约

1.0 起扩展点 API 视为稳定,破坏性变更走 major 版本,二开投入可长期沿用。

适用于这些业务场景

凡是「有固定 Excel 模板、需要在后端批量生成高保真 PDF」的业务,都可以用这个库搬上线。

检验检测报告

检测报告、原始记录模板化,照片 / 条码 / 印章一键嵌入,批量出 PDF 支撑 CMA / CNAS 体系报告编制。

· 报告模板 · 图文码混排

票据与小票打印

自定义纸张宽高直读模板文件,横向页自动补 /Rotate,WPS 打印预览与 Clodop 正确选到横向纸。

· 自定义纸张 · 横向标记(Pro)

物流与资产标签

条形码 / 二维码标记两版内置,data 传数组逐页渲染(Pro),一份模板批量出成百上千张标签。

· 条码二维码 · 多页批量(Pro)

政企申报表单

各类固定格式申报表、统计表模板化,数字格式自动继承,产出与 Excel 所见一致的规范 PDF。

· 格式保真 · 规范产出

水印与叠章(Pro)

watermark 文本水印浮层,作废 / 已审核 / 机密叠章,字号自适应、层级可置于模板上下方。

· 文本水印 · 层级堆叠

后端服务集成

Node 服务批量生成,Pro 并发限流 + 内存准入守卫 + 参数化规模守卫,负载下始终为其他服务保留余量;社区版固定上限 + 单并发。

· 并发限流 · 内存护栏(Pro)

社区版 × Pro,
选对你的生产档位

社区版以 Apache-2.0 开源免费,完整提供「模板标记 → HTML → PDF」核心链路,图片 / 条码 / 二维码富媒体标记与明细行内置,三层扩展机制,单份图文码报告可独立走通, 不是功能阉割的试用版;Pro 商业授权面向高要求生产场景,叠加专有保真、水印与图片压缩、批量出单与生产护栏, 按产品买断、随产品分发免版税。两版扩展同源同契约,插件与自定义标记一次编写、两版通用。

Community · 开源

社区版 xlsx2pdf

Apache-2.0 许可,商用自由。公开 npm 安装,5 分钟跑通「Excel 模板 → 高保真 PDF」核心链路,单份图文码报告可独立走通,适合评估验证与轻量单页出单。

$npm ixlsx2pdfApache-2.0
  • 核心链路全开放:excel2pdf / excel2html,模板路径 / URL / Buffer 入参
  • 样式与格式保真:合并格 / 富文本 / numFmt 自动继承,同格多标记混排
  • 富媒体与明细行内置:image / barcode / qrcode(1.1.0+)+ 浮层参数,#数组.字段 明细行索引映射(1.2.0+)
  • 标准纸张 + 内置 Chrome:7 种具名纸张、方向边距,ESM/CJS + TS 类型
  • 扩展机制同源:三层扩展点 + 两级注册 + 自定义标记语法 + helpers 7 件
  • 善意安全默认:模板体积 / 单元格数固定上限、固定单并发排队,社区 issue 支持
生产推荐
Pro · 商业授权

Pro @krstation/xlsx2pdf-pro

按产品买断授权,随产品分发免版税。在社区版之上叠加专有保真、水印与图片压缩、批量出单与生产护栏,私有 npm 源授权交付,含 SLA 工单与专属群支持。

$npm i@krstation/xlsx2pdf-pro私有源 · 授权后安装
  • 专有保真:精确列宽换算 + fontGuard 字体守卫,fitToPage 单页自适应 + minFontSize
  • 富媒体增强:watermark 文本水印 + sharp 压缩管线 + DPI 物理尺寸, 图片 / 条码 / 二维码社区版已内置
  • 批量与页面完整性:data 数组逐页出单、自定义纸张直读、scale 精确缩放、pageRotate
  • 生产护栏:maxConcurrency 限流 + memoryGuard 内存准入 + 守卫参数化
  • 高级 helpers + 服务:optimizeImage 图片压缩工具,SLA 工单 + POC

功能矩阵逐项对比

✓ 支持◐ 有限支持— 不含
能力社区版开源 Apache-2.0 · npm xlsx2pdfPro 商业版买断授权 · @krstation/xlsx2pdf-pro
核心链路 · 双版同源
excel2pdf / excel2html 核心链路✓✓
text 标记 · 默认值 · 嵌套点路径取值✓✓
同格多标记混排 · 段级富文本继承✓✓另含段级独立 minsize
样式保真合并格 / 字体 / 字色 / 背景 / 边框 / 富文本✓✓
numFmt 数字格式自动继承✓✓
标准纸张 7 种 + 方向 + 边距✓✓
内置 Chrome 自动安装 / 外部浏览器复用✓✓
ESM / CJS 双产物 + TypeScript 类型✓✓
image / barcode / qrcode 富媒体标记本地路径 / URL / base64,bwip-js 生成码图✓1.1.0 起内置,纯 JS 尺寸归一(@96DPI),不压缩✓sharp 压缩 + DPI 感知物理尺寸
浮层参数 w/h/ox/oy/zindex/opacity层级堆叠 / 透明度 / 偏移定位✓✓
#数组.字段 明细行索引映射逐行重复取数组下一项,行数由模板定✓1.2.0 起内置✓
三层扩展点 + 两级注册 + 自定义标记语法✓helpers 7 件(含 generateCode / bufferToDataUrl)✓同机制 + watermark 内置类型 + optimizeImage(8 件)
模板规模守卫文件体积 / 单元格数上限✓固定上限,不可配✓可参数化调整
保真与页面 · Pro 核心付费墙
列宽换算◐公开公式近似✓精确换算 + fontGuard 字体守卫
内容超页处理◐Chrome 原生分页,可能截断 / 意外跨页✓fitToPage 单页自适应 + minFontSize,超页不裁剪
自定义纸张{width,height} 传参 / 文件内宽高直读 / 单位换算—✓mm/cm/in/pt 换算,小票标签纸
scale 1~400 精确缩放—✓
pageRotate 国产打印链路适配—✓/Rotate 90,WPS / Clodop 正确选纸
富媒体增强与批量 · Pro
图片自动压缩 + DPI 物理尺寸sharp 缩至显示尺寸 + JPEG 转换—纯 JS 尺寸归一,不压缩✓高 DPI 图片自动缩小
watermark 文本水印作废 / 已审核叠章,字号自适应—自定义 handler 可返回水印浮层✓zIndex / opacity 堆叠,minsize / lineheight
autoInsertImage 无标记格自动插图—✓
data 数组多页批量每元素渲染一页—单记录 + #明细行,数组传参报引导错✓一份模板出百单
生产与服务
maxConcurrency 并发限流—固定单并发,超限排队✓标签页限流排队
memoryGuard 内存准入守卫—✓cgroup / 宿主机探测 + 排队
技术支持社区 issue✓SLA 工单 + 专属群 + 免费 POC
授权方式Apache-2.0,商用自由商业 EULA,按产品买断、随产品分发免版税
单产品 ISV 推荐

专业版

单个产品集成,小团队起步

买断授权 · 询价1 个产品 · ≤3 开发席位 · 随产品分发免版税
  • 已交付版本永久使用权 + 首年更新与支持
  • 5×8 工单支持,48h 响应
  • 私有 npm 源授权交付 + 接入指导
  • 次年起可选维护(授权费 20%/年)
获取报价

企业版

多产品矩阵 / 私有化部署团队

买断授权 · 询价≤3 个产品 · 法人内席位不限 · 离线部署包
  • 含专业版全部权益,多产品授权
  • 离线部署包 + 私有源镜像,内网可装
  • 7×12 工单支持,24h 响应
  • 次年起可选维护(授权费 20%/年)
获取报价

OEM / 源码授权

平台厂商深度集成 / 源码可控诉求

专项授权 · 询价OEM 集成授权 / 源码授权 · 按范围报价
  • OEM:嵌入自有平台对外分发
  • 源码授权:可选 escrow 托管
  • 4h 响应,专属对接通道
  • 授权范围与条款按 NDA 商定
商务洽谈
买断模型说明:买断 = 已交付版本永久使用权 + 首年更新与支持;次年起可选维护(授权费 20%/年),不续维护不影响已交付版本继续使用与随产品分发。授权按产品计、随产品分发免版税,另提供可选年度租约。正式报价按 NDA 提供;评估阶段可申请免费 POC 与 30 天评估授权。社区版始终开源免费,Pro 专属键经 option 传入会显式报错并附引导,configure 则容忍忽略并按固定上限兜底,不静默降级。

免费 POC:用你的真实模板验证保真度

提供 3 个真实业务模板,48 小时内出具基准对比报告(列宽 / 超页 / 富媒体 / 批量),并可申请 30 天 Pro 评估授权。先验证效果,再谈采购。

从社区版开始,撞上生产再升 Pro

一条命令跑通开源核心链路,图文码单份报告直接生产可用;需要精确保真、水印压缩、批量出单与生产护栏时,Pro 买断授权随产品分发免版税。