PDFKit JavaScript (Node.js) 完全指南：安装、方法与实战示例

PDFKit 简介

PDFKit 是一个强大且灵活的库，用于在服务器端使用 JavaScript (Node.js) 生成 PDF 文档。它为开发者提供了对 PDF 创建过程的完全控制：从简单的文本文档到包含表格、图片、图形和交互元素的复杂多页报告。PDFKit 无需安装 PhantomJS 或 Puppeteer 等额外依赖，完全基于纯 JavaScript 运行，使其成为高负载服务器应用的理想选择。

为什么需要这个库？在现代 Web 开发中，经常需要以编程方式生成 PDF 文档：发票、送货单、报告、证书、合同等。PDFKit 优雅而高效地解决了这个问题。与可能缓慢且不可预测的 HTML 转 PDF 转换器不同，PDFKit 让您直接访问 PDF 模型：您自己定义每个元素的坐标，管理字体、颜色和页面布局。当需要精确定位元素或处理非标准格式时，这一点尤为重要。

该库由社区积极维护，拥有丰富的文档，并被全球数千家公司用于生产环境。PDFKit 支持 PDF 格式的所有主要功能：嵌入字体（包括中文）、处理图像（JPEG、PNG、SVG）、创建注释、超链接、书签以及文档加密。凭借模块化架构和流式写入能力，PDFKit 既适合创建小型文档，也适合生成数 GB 的大型 PDF 文件。

安装 PDFKit

PDFKit 通过 npm 包管理器分发。使用标准命令安装：

npm install pdfkit

如果使用 TypeScript，可能需要安装额外的类型定义：

npm install pdfkit @types/pdfkit

如果您使用 Yarn：

yarn add pdfkit

安装完成后，库即可使用。无需任何额外依赖或系统要求——在任何支持 Node.js 的平台（Windows、macOS、Linux）上都能“开箱即用”。

快速入门：最小工作示例

创建一个文件 hello-pdf.js 并添加以下代码：

const PDFDocument = require('pdfkit');
const fs = require('fs');

// 创建一个新的 PDF 文档
const doc = new PDFDocument();

// 指定输出文件路径
doc.pipe(fs.createWriteStream('hello.pdf'));

// 添加文本
doc.fontSize(25)
   .text('你好，世界！', 100, 100);

// 结束文档
doc.end();

console.log('PDF 已创建：hello.pdf');

运行脚本：

node hello-pdf.js

在当前目录下会生成一个 hello.pdf 文件，其中包含“你好，世界！”文本。这个示例展示了 PDFKit 的基本工作原理：创建文档、添加内容并保存结果。

PDFKit 核心方法与类

PDFKit 提供了丰富的 API 用于处理 PDF 文档。下面介绍日常开发中常用的核心方法。

1. new PDFDocument(options) — 文档构造函数

签名： new PDFDocument([options])

描述： 创建一个新的 PDF 文档实例。参数 options 是一个对象，用于设置页面尺寸、边距、方向、元数据和其他配置。

const doc = new PDFDocument({
  size: 'A4',              // 页面尺寸（A4、Letter、Legal 等）
  layout: 'portrait',      // 方向：'portrait'（纵向）或 'landscape'（横向）
  margins: {               // 页边距