每周 290 万次下载的 pptxgenjs，核心代码基本是一个人写的

昨天刚拆完一个 AI 做 PPT 的工具，把截图翻译成原生幻灯片那种。今天想往下再挖一层，挖到那类工具脚下的地基，pptxgenjs。

先给你看一组我抓下来的数字。npm 上每周下载 290 万次，GitHub 6113 Star，MIT 协议，2016 年 2 月创建。听起来是个健康的中型开源项目对吧。

再看另一组数字。主分支最后一次代码提交停在 2025 年 6 月 25 日，到今天十四个月，一行代码没动过。294 个 open issue，64 个 open PR，全部无人认领。贡献榜第一名 gitbrent，2467 次提交，第二名 clubajax，57 次。

差了 43 倍。

这个库的核心代码，基本就是 Brent Ely 一个人写的，写了九年。

一个每周被下载 290 万次的基础库，和一个十四个月没人维护的仓库，是同一个东西。今天这篇就把这两件事拆开看，它凭什么被用这么多，又为什么会停在这里。

.pptx 根本不是「文件」，是个压缩包

很多人对 pptxgenjs 的第一反应是，用 JavaScript 生成 PowerPoint，那机器上得装 Office 吧？

不用。一台也没有也行，连浏览器里都能跑。

秘密在于 .pptx 这个后缀的本质。你把任何一个 pptx 文件后缀改成 .zip，解压，会看到一堆 XML 文件。[Content_Types].xml 声明包里有啥，ppt/presentation.xml 描述演示文稿结构，ppt/slides/slide1.xml 是第一页幻灯片的内容，ppt/media/ 里躺着图片，一切内容都是纯文本 XML，靠一套叫 OOXML 的开放标准组织起来。

pptxgenjs 做的事情就变得很朴素了，用字符串模板把这些 XML 一份份拼出来，再用 JSZip 打包成 zip，改个后缀，完事。

我在源码里找到了它的打包清单，在 src/pptxgen.ts 的 exportPresentation 函数里，流程分五步。第一步先把所有图片视频编码成 base64，第二步建目录骨架，_rels、docProps、ppt/slides、ppt/media 一共十来个文件夹，第三步逐个生成 XML 塞进去，第四步处理图表和媒体的关系文件，第五步 zip.generateAsync 一次性压缩输出。

zip.file('[Content_Types].xml', genXml.makeXmlContTypes(...))
zip.file('ppt/presentation.xml', genXml.makeXmlPresentation(this))
zip.file(`ppt/slides/slide${idx + 1}.xml`, genXml.makeXmlSlide(slide))
// 最后
zip.generateAsync({ type: 'blob', compression: 'DEFLATE' })

整个库的运行时依赖，理论上有意义的只有一个 jszip。没有 Office 互操作组件，没有 headless PowerPoint，没有 puppeteer。这也是它能跑在 Node、React、Vite、Electron 和纯浏览器里的原因，哪里能拼字符串，哪里就能生成 pptx。

一万行 TypeScript，十个文件的分工

把仓库克隆下来数了一遍，src 目录总共 10125 行 TypeScript，十个文件。

一万个文件行数撑起一个品类的事实标准，这个密度本身就说明 .pptx 格式没想象中那么难啃，也说明作者写得克制。

API 设计是典型的收集再渲染模式。你调 slide.addText()、addImage()、addChart()，Slide 类只是把参数原样收进 _slideObjects 数组，什么都不算。直到你调 writeFile()，gen-xml.ts 才开始遍历所有对象，逐个转成 XML 片段。

整条管线从上到下长这样。

这个两段式设计让同一份中间表示可以流向不同输出，浏览器拿 blob，Node 拿 Buffer 或者文件流，测试还能直接断言 XML 字符串。

最惊艳的一手，图表里藏了一个 Excel

pptxgenjs 支持原生图表，柱状图、饼图、折线图，不是贴图，是真的图表对象，可以在 PowerPoint 里改颜色的那种。

你在 PowerPoint 里双击一个原生图表，会弹出一个 Excel 表格让你编辑数据。你有没有想过这个 Excel 从哪来的？

答案在 gen-charts.ts 里，我读到的时候确实愣了一下。它内部又 new 了一个 JSZip 实例，变量名叫 zipExcel，然后手写了 xl/workbook.xml、xl/sharedStrings.xml、xl/worksheets/sheet1.xml、xl/styles.xml 一整套 xlsx 格式的部件，自己打包成一个迷你 Excel 文件，塞进 pptx 包的 ppt/embeddings/ 目录里。

const zipExcel = new JSZip()
zipExcel.folder('xl/worksheets')
zipExcel.file('xl/workbook.xml', ...)
zipExcel.file('xl/sharedStrings.xml', ...)

zip 里嵌 zip。

为的就是保住那条交互链路，用户双击图表，PowerPoint 打开内嵌工作簿，改个数，图表跟着变。少写任何一个部件，这个链路就断了。

这是全库最见功力的地方。做格式生成器不难，难的是把目标软件的隐性期待也一并满足。

一个有点鲁莽但很实用的启发式

OOXML 里的坐标单位是 EMU，1 英寸等于 914400 EMU。API 允许你传英寸，也允许直接传 EMU，那库怎么区分你传的是哪种？

gen-utils.ts 里有个 getSmartParseNumber，逻辑直白到可爱。数字小于 100，当成英寸，乘 914400。大于 100，认定肯定不是英寸（原注释，any value over 100 damn sure isnt inches），原样返回当 EMU 用。

你造一个 500 英寸宽的文本框？这个库不惯着你。但你传 3.5 它知道是英寸，传 914400 它知道是 EMU，真实世界两种需求都覆盖了，代码只有十几行。

工程上这叫启发式，说难听点叫赌。但赌注下得对，十年了没人因为这个找上门。

好架构，但生成阶段会弄脏你的数据

讲完好的，讲讲我在源码里亲手验证到的问题。

gen-xml.ts 第 519 到 524 行，生成阴影 XML 的时候，它把单位换算的结果直接写回调用者传入的 options 对象上。blur 乘 12700 转 point，angle 乘 60000 转 OOXML 角度单位，opacity 乘 100000。

slideItemObj.options.shadow.blur = valToPts(slideItemObj.options.shadow.blur || 8)
slideItemObj.options.shadow.angle = Math.round((slideItemObj.options.shadow.angle || 270) * 60000)

单看没事。但前端工程里共享一个样式对象再正常不过了，定义一个 SHADOW 常量，十个卡片复用。于是在导出时，第一个 shape 把 blur 乘了 12700，第二个 shape 拿到的已经是换算过的值，再乘 12700，指数级膨胀。

整个膨胀回路长这样。

issue #1527 里有人贴出了后果，XML 里出现 dir="1.1664e+21"，科学计数法直接漏进了 OOXML，远超合法范围，LibreOffice 转 PDF 时当场崩溃。

「生成过程不改写用户输入」本是生成器的基本操守，这里破戒了。而且 bug 报告挂在 issue 区一个多月，没人修。

维护停滞还养出了一些小毛病。package.json 的 dependencies 里躺着 image-size，我 grep 了整个 dist 产物，零引用，一个幽灵依赖，但它的安全公告会跟着你的 npm audit 一起出现，没法打补丁，只能等上游删。旁边还有个 https@1.0.0，npm 上的同名占位包，作用只是转发 Node 内置模块，纯粹的历史手滑。@types/node 也被放进了 dependencies 而不是 devDependencies。

坦白讲，都不是致命伤。但每一处都在说同一句话，这里很久没人扫地了。

社区已经动手分叉了

2026 年 8 月 15 日，issue #1525 出现了一篇分叉公告。一个叫 lofcz 的开发者说，他在做自己的产品时受不了 issue 积压，把散落在各处的修复整合成了一个 fork，起名 pptxgenjs-plus，新构建系统，还搭了一套 Rust 写的测试基建，对着真实 PowerPoint 跑回归，防止修一个坏一个。

他甚至给了一条一行命令的迁移路径，npm uninstall pptxgenjs，装 pptxgenjs-plus，改一行 import，完事。

我查了下这个 fork 的数据，14 个 Star，每周下载 1646 次，和原库的 290 万比是九牛一毛。分叉解决了代码问题，解决不了生态惯性问题，你想想看，那 290 万次下载里，绝大多数用户可能根本不知道原库停更了。

顺带说一个选型时真正要紧的边界。pptxgenjs 只能写，不能读。你没法用它打开一个现成的 pptx 改两页再存回去，它的世界是单向的，从代码到文件。要读改写，Python 生态的 python-pptx 是更成熟的选择，读写都行。同为 JS 系的还有 officegen（维护同样缓慢）、专注 Word 的 docx（活跃）、Java 的 Apache POI（重量级全能）。pptxgenjs 的独特位置是，纯前端可跑、零 Office 依赖、只管生成，恰好卡住了浏览器端导出这个场景。

笨办法的胜利，和它的代价

拆完这个仓库，我一直想着两件事。

第一件事可以叫「开放标准即杠杆」。当一种文件格式是公开规范，任何语言任何人都可以用最笨的方式实现它，拼字符串。没有黑盒，没有授权费，没有平台锁定。pptxgenjs 用一万行代码撬动了每周 290 万次下载，靠的不是什么高深架构，是它敢把 OOXML 规范当成协议来实现。同样思路在 exceljs、docx 这些库身上反复验证过。下次你面对一个封闭难搞的格式问题，先去查查它的规范文档，说不定十几个字符串模板就解了。

第二件事关于选型。这个库今天依然能用，290 万周下载不是假的，v4.0.1 生成的文件在 PowerPoint、Keynote、WPS 里打开都没问题。但如果你的业务关键路径压在 pptx 导出上，我的建议是，锁死版本号，别用 ^ 浮动引用，跑一遍自己的回归测试再每次升级。至于要不要迁去 pptxgenjs-plus，再观察几个月它的存活曲线。一个人撑九年是传奇，也是风险，传奇的部分属于 Brent Ely，风险的部分属于每一个 npm install 的人。

大家好，我是若风，这篇就到这。如果你在做的 AI 产品正好用到了 pptx 导出，评论区聊聊你踩过的坑。