docx-convert-pdf

Convert .docx to .pdf on a headless Linux server with the best possible fidelity and fast conversion (typically < 5s per file after warmup). Wraps LibreOffice headless. Zero runtime dependencies.

中文说明：在无桌面的 Linux 服务器上将 .docx 转换为 .pdf，转换效果最佳、速度极快（预热后通常单个文件 < 5 秒）。底层调用 LibreOffice headless，零运行时依赖。

Why LibreOffice / 为什么用 LibreOffice

.docx is a complex layout format. Only a full layout engine reproduces Word's pagination, headers, tables, images, and fonts. Pure-JS converters lose this fidelity, so this package shells out to LibreOffice headless — the best free option on headless Linux.

.docx 是复杂的版式格式，只有完整的排版引擎才能还原 Word 的分页、页眉页脚、表格、图片与字体。纯 JS 转换器会丢失这些还原度，因此本包直接调用 LibreOffice headless —— 这是无桌面 Linux 上效果最好的免费方案。

Prerequisites / 前置依赖

Install LibreOffice and fonts (the package will error with this hint if soffice is missing):

安装 LibreOffice 与字体（若找不到 soffice，本包会报错并给出如下提示）：

sudo apt update
sudo apt install -y libreoffice-core libreoffice-writer libreoffice-impress \
  fonts-crosextra-carlito fonts-noto-cjk

• fonts-crosextra-carlito (Carlito) is metric-compatible with Calibri — Word's default.
• fonts-noto-cjk covers Chinese/Japanese/Korean text so CJK glyphs render correctly.

• fonts-crosextra-carlito（Carlito）与 Word 默认字体 Calibri 字距兼容。
• fonts-noto-cjk 覆盖中日韩文字，确保中文等字形正确渲染、不出乱码。

To point at a non-standard binary, set DOCX_CONVERT_PDF_SOFFICE=/path/to/soffice.

如 soffice 不在默认路径，可设置环境变量 DOCX_CONVERT_PDF_SOFFICE=/path/to/soffice 指定二进制路径。

Install / 安装

npm install docx-convert-pdf

API / 接口

import { convertDocxToPdf } from 'docx-convert-pdf';

const out = await convertDocxToPdf('input.docx', 'output.pdf');
// -> '/abs/path/to/output.pdf'

// Derive output next to the input, or into a directory:
// 也可不指定输出文件名，按输入同目录或指定目录生成：
await convertDocxToPdf('input.docx', { outdir: './out', timeout: 30000 });

Options / 选项

| option | type | default | description (EN) | 说明（中文） | | ----------- | -------- | -------------------------------- | -------------------------------------------- | --------------------------------------------- | | output | string | input name + .pdf | Explicit output path. | 显式指定输出 PDF 路径。 | | outdir | string | input directory | Output directory (ignored if output set). | 输出目录（指定了 output 时忽略）。 | | timeout | number | 30000 | Conversion timeout in ms. | 转换超时，单位毫秒。 | | profileDir| string | ~/.cache/docx-convert-pdf/lo-profile | LibreOffice user profile dir (kept warm). | LibreOffice 用户配置目录（保持预热复用）。 | | sign | object | — | Digitally sign the PDF (see Digital signing). | 对 PDF 做数字签名（见"数字签名"章节）。 |

CLI / 命令行

npx docx2pdf input.docx                 # -> input.pdf
npx docx2pdf input.docx output.pdf
npx docx2pdf input.docx --outdir ./out
npx docx2pdf input.docx --timeout 60000

# convert and sign in one step / 转换并同时签名
npx docx2pdf input.docx signed.pdf --sign-cert cert.pfx --sign-passphrase secret
# sign an existing pdf / 对已有 PDF 签名
npx docx2pdf sign input.pdf cert.pfx signed.pdf --sign-passphrase secret

Signing flags: --sign-cert, --sign-passphrase (or env DOCX_CONVERT_PDF_CERT_PASSPHRASE), --sign-reason, --sign-location, --sign-contact, --sign-subfilter pades|pkcs7.

Digital signing / 数字签名

Digitally sign the PDF with a PKCS#12 (.pfx) certificate using PAdES (ETSI.CAdES.detached) by default. After signing, any modification to the PDF invalidates the signature — PDF readers show "document has been altered". This is the cryptographic guarantee that tampering is detectable (unlike PDF permission flags, which are advisory and trivially removed).

用 PKCS#12（.pfx）证书对 PDF 做 PAdES（ETSI.CAdES.detached，默认）数字签名。签名后任何改动都会使签名失效，阅读器会提示"文档已被更改"。这是"改动可被察觉"的密码学保证（不同于 PDF 权限位——权限位只是建议性的，可被轻易移除）。

Signing is an optional feature: it uses @signpdf + node-forge, declared as optionalDependencies (installed by default; pass --omit=optional to keep the convert-only path dependency-free). If missing, signing throws a clear install hint.

签名是可选功能：使用 @signpdf + node-forge，声明为 optionalDependencies（默认安装；如需保持"仅转换、零依赖"，安装时加 --omit=optional）。缺失时会给出明确的安装提示。

Generate a self-signed certificate / 生成自签名证书

For internal/trusted scenarios a self-signed certificate suffices. For public distribution, use a CA-issued certificate.

内部或可信场景用自签名证书即可；对外发布请使用 CA 颁发的证书。

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -nodes \
  -subj "/C=CN/O=your-org/CN=your-name" \
  -addext "basicConstraints=critical,CA:FALSE" -addext "keyUsage=critical,digitalSignature"
openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx -passout pass:SECRET

API

import { convertDocxToPdf, signPdf } from 'docx-convert-pdf';

// Convert + sign in one call / 转换并同时签名
await convertDocxToPdf('input.docx', 'output.pdf', {
  sign: { certPath: 'cert.pfx', passphrase: 'SECRET', reason: 'I approve', location: 'CN' },
});

// Sign an existing PDF / 对已有 PDF 签名（默认输出 <name>-signed.pdf）
await signPdf('input.pdf', { certPath: 'cert.pfx', passphrase: 'SECRET' });

SignOptions: certPath, passphrase, reason, location, contactInfo, name, subFilter ('pades' default | 'pkcs7'), signatureLength, widgetRect, output.

Verify / 验证

pdfsig output.pdf          # poppler: shows "Signature Validation: Signature is Valid"

Performance / 性能

A shared, pinned LibreOffice user profile is created once and reused, so the first conversion pays a one-time cost and later conversions are fast (font/config caches stay warm). Input is copied into a fresh temp workdir, converted, and the resulting PDF is moved to the final path — safe for concurrent calls.

共享且固定的 LibreOffice 用户配置只创建一次并复用：首次转换承担一次性开销，后续转换很快（字体/配置缓存常驻）。每次转换先把输入复制到独立临时目录，再转换、把生成的 PDF 移动到最终路径——支持并发调用，互不干扰。

License

MIT