事情要从一个内部知识库项目说起。那时候，产品经理走过来提了一个听起来再简单不过的需求：“咱们知识库里存了那么多 PDF 文档，用户在列表页预览的时候，Neng不Neng直接展示文档的缩略图？点一下缩略图再打开全本，体验会好hen多。”

听起来确实合情合理，对吧？但现实往往比骨感geng骨感——我们的数据库里只有孤零零的 PDF 文件，压根就没有什么缩略图。于是摆在面前的任务就hen清晰了：如何从 PDF 文件中生成缩略图？

第一阶段：那个“几十行代码”的下午

Zui初的需求真的hen简单，就是给知识库用，Neng生成个图就行。我寻思着这Neng有多难？一番调研后发现，Node.js 生态里虽然有一些 PDF 相关的库，但要么功Neng太重、要么只Neng跑在浏览器端、要么 API 设计极其反人类。Zui后决定，不如基于 pdf-parse 或者类似的底层Neng力，自己封装一个轻量级的截图工具。

于是我在项目里写了个 utils/pdfSnapshot.ts。那时候的想法hen单纯，Neng跑就行，别整那些虚的。核心逻辑大概长这样：

import { PDFParse } from 'pdf-parse';
export async function snapshotPdf {
  // 读取文件
  const pdfBuffer = await readFile;
  const pdfParser = new PDFParse;
  // 调用截图接口
  const result = await pdfParser.getScreenshot({
    partial: pages,
    scale: 1.5,
    imageBuffer: true,
  });
  // 返回结果
  return result.pages.map(page => ({
    page: page.pageNumber,
    data: Buffer.from,
  }));
}

嗯，几十行代码，一气呵成，需求搞定，下班！那时候心里还挺美，觉得这事儿就这么翻篇了。本以为写个工具函数就完事了没想到这个小需求Zui终演变成了一个完整的 npm 包。下面就来聊聊这个渐进式的演化过程。

第二阶段：当“脚本”遇上“生产环境”

好景不长，没过多久，隔壁组的同事找过来了：“嘿，听说你写了个 PDF 截图的工具？我们这边有个文档预处理服务也需要这个功Neng，Neng不Neng给我们用用？”

既然要给其他模块用了之前那种“写死在业务代码里”的Zuo法就行不通了。于是开始了第一次重构：我把这个函数从业务项目里抽出来放到了一个独立的内部模块里。但抽离的过程中发现了一些问题，这些问题在单文件脚本里不明显，一旦变成公共库，就变得格外刺眼。

内存泄漏的噩梦

Zui头疼的问题是内存。随着处理量的增加，服务器的内存占用一路飙升，Zui后直接 OOM崩溃。经过一番排查，罪魁祸首是 PDF 解析库。

为什么要用子进程？因为 pdfjs-dist在解析 PDF 时会在 V8 堆上分配大量内存。即使你在代码里调用了 destroy 方法，试图手动释放，但在 Node.js 的单线程模型下这些内存往往hen难完全回收，碎片化严重。Ru果在主进程里处理大量 PDF，内存会越积越多，Zui后只Neng重启进程。

解法hen简单也hen粗暴——用子进程。子进程退出后操作系统会自动回收它占用的所有内存，干净利落，不留后患。

IPC 通信的权衡

确定了子进程方案，下一个问题就是通信。子进程算完了图，怎么把结果给主进程？

这里有个细节值得一提：IPC 通信只传文件路径，不传 Buffer。为什么？因为 IPC 传输大数据hen慢。一张高清截图可Neng有几 MB，Ru果通过 IPC 传 Buffer，序列化和反序列化的开销巨大，性Neng会hen差。所以我们让子进程把截图写到临时目录，IPC 只传路径和元数据，主进程再按需读取。

整个项目的目录结构也随之发生了变化，变得geng加清晰：

src/
├── core/
│   ├── snapshot.ts      # 核心截图函数
│   ├── pdf-info.ts      # 获取 PDF 信息
│   └── worker.ts        # 子进程 Worker
├── utils/
│   ├── input-normalizer.ts   # 输入归一化
│   ├── page-resolver.ts      # 页码解析
│   ├── output-formatter.ts   # 输出格式化
│   └── worker-manager.ts     # 子进程管理
├── cli/
│   └── index.ts         # 命令行入口
├── types.ts             # 类型定义
├── errors.ts            # 错误类
├── constants.ts         # 常量
└── index.ts             # 导出入口

第三阶段：从“工具”到“产品”的蜕变

又过了一段时间，其他团队的同事也找过来了：“你们那个 PDF 截图工具挺好用的，我们想在另一个项目里用，Neng不Neng发个 npm 包？对了我们有个批量处理的场景，Neng不Neng加个进度回调？还有，我们运维同学想在脚本里用，Neng不Neng支持命令行？”

好家伙，需求越来越多了。既然要发 npm 包，那就得认真对待了。于是有了这次比较彻底的重构。Zui终，这个工具从一个几十行的函数，演变成了一个结构完整的 npm 包——@guangmingz/pdf-snapshot。

输入归一化：统一处理多种输入格式

这是整个设计中Zui关键的一环。用户传进来的东西千奇百怪：可Neng是本地文件路径字符串，可Neng是内存里的 Buffer，甚至是一个网络下载的 Stream。Ru果让业务方自己去判断类型，那就太烦人了。

不管用户传什么格式，Zui终dou归一化为文件路径，后续逻辑只需要处理文件路径即可。这种「归一化」的设计模式在hen多场景下douhen实用。

export async function normalizeInput: Promise<{ path: string; isTempFile: boolean }> {
  // 文件路径：直接使用
  if  {
    return { path: input, isTempFile: false };
  }
  // Buffer / Stream：写入临时文件
  const tempPath = join, `pdf-${randomUUID}.pdf`);
  if ) {
    await writeFile;
  } else {
    // Stream
    const chunks: Buffer = ;
    for await  {
      chunks.push;
    }
    await writeFile);
  }
  return { path: tempPath, isTempFile: true };
}

控制力：超时与取消

处理大文件时用户可Neng等不及想取消；或者子进程卡死了需要超时兜底。这两个Neng力是生产环境必备的。

取消Neng力基于标准的 AbortController

const controller = new AbortController;
setTimeout => controller.abort, 5000);  // 5秒后取消
try {
  await snapshotPdf;
} catch  {
  if  {
    console.log;
  }
}

超时控制在子进程管理器里实现：

const timer = setTimeout => {
  child.kill;  // 强制杀死子进程
  reject);
}, timeout);

进度回调：让等待不再焦虑

批量处理时用户需要知道当前进度。虽然子进程是一次性处理所有页面的，但我们至少Ke以在「开始」和「完成」两个时机通知用户：

await snapshotPdf('./document.pdf', {
  pageRange: ,
  onProgress:  => {
    // progress.stage: 'preparing' | 'completed'
    // progress.percent: 0 | 100
    console.log;
  },
});

为什么不支持逐页进度？因为 pdf-parse 的 getScreenshot 是一次性处理所有页面的，中间没有回调钩子。Ru果要实现逐页进度，需要改成逐页调用，但这样会有性Neng问题。权衡之下选择了「阶段进度」的方案。

第四阶段：拥抱 CLI 与 AI Agent

为什么要Zuo CLI？除了方便运维同学写脚本，还有一个重要原因——方便 AI Agent 调用。

现在各种 AI 编程助手越来越流行，它们通常通过命令行来调用工具。Ru果你的工具只有 API 没有 CLI，AI 就hen难直接使用。CLI 的实现基于 commander，核心是把命令行参数映射到 snapshotPdf 的 options：

program
  .argument
  .option
  .option
  .option
  .option
  .action => {
    const results = await snapshotPdf(input, {
      output: 'file',
      outputDir: opts.output,
      pageRange: parseRange,
      pages: parsePages,
      scale: parseFloat,
    });
    console.log;
  });

还贴心地加了进度条：

⏳ 正在截图...   100% | 10 / 10 页
✅ 完成！Yi保存 10 张截图到 ./pdf-screenshots

pdf-snapshot 的 CLI 使用起来hen简单：

# 截取第 1-5 页
pdf-snapshot -r 1-5 -o ./output document.pdf
# 截取指定页
pdf-snapshot -p 1,3,5 document.pdf
# 从标准输入读取
cat document.pdf | pdf-snapshot -o ./output -r 1-3 -
# 仅查kan PDF 信息
pdf-snapshot --info document.pdf

回顾 pdf-snapshot 的演化过程，其实挺有代表性的。hen多时候我们写的工具函数，一开始只是为了解决眼前的问题，但随着需求的增加和使用场景的 ，它会逐渐演化成一个geng通用、geng健壮的模块。

从Zui初那个“几十行代码搞定下班”的简单脚本，到后来为了解决内存泄漏而引入的子进程架构，再到为了满足团队协作而进行的模块化重构，Zui后到为了适应 AI 时代而添加的 CLI 支持。每一步dou不是凭空设计出来的，而是被实际需求“逼”出来的。

关键是要在演化过程中保持代码的可维护性和可 性。子进程隔离、输入归一化、取消超时机制……这些设计不是一开始就有的，而是在实际使用中逐步发现问题、解决问题后沉淀下来的。

Zui后Ru果你也有 PDF 截图的需求，欢迎试试 pdf-snapshot！有问题欢迎提 Issue，有改进想法欢迎 PR！GitHub 地址：pdf-snapshot。

---