# @docx-editor\.dev/docx-to-pdf 中文文档

规范地址：https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/

版本：2\.38\.0
npm 元数据更新时间：2026-11-16T13:49:26.752Z
中文译文更新时间：2026-11-16T13:52:08.033Z
软件包许可：LicenseRef-EigenPal-Pro-Evaluation-1\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40docx-editor.dev/docx-to-pdf
原文对照：https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/?lang=original
项目主页：https://docx-editor.dev/
源码仓库：https://github.com/eigenpal/docx-editor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.4 MB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.16\.0 \|\| \>=22\.3\.0
- 运行依赖：4 个
- peer 依赖：@docx-editor\.dev/core ~2\.38\.0，@docx-editor\.dev/fonts-cjk ~2\.38\.0
- 首次发布：2026-09-24T08:59:30.302Z
- 最新版本发布：2026-11-16T13:49:26.346Z
- 近 30 天下载量：4969（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

在 Node.js 上将 DOCX 转换为 PDF ,并带有可搜索的文本,嵌入字体和注释.

## 安装

```sh
npm install @docx-editor.dev/docx-to-pdf
```

也可以使用：`pnpm add @docx-editor.dev/docx-to-pdf`、`yarn add @docx-editor.dev/docx-to-pdf`、`bun add @docx-editor.dev/docx-to-pdf`

## README

[![DOCX Editor by EigenPal](https://raw.githubusercontent.com/eigenpal/docx-editor/main/.github/assets/readme-logo-light.svg)](https://www.docx-editor.dev/)

# DOCX 到 PDF

`@docx-editor.dev/docx-to-pdf` 在Node.js上将DOCX文档转换为PDF. 它使用 Core 的 pagination,字体分辨率,以及定位的glyphs来生成可搜索文本.

软件包使用 [EigenPal Pro 许可证](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/LICENSE.md)生产用途需要商业协议.

## 在你开始之前

使用节点.js 20.16.0或后期为20x放行,或节点.js 22.3.0或后期. 转换器需要Web Assembly及其被打包的字体资产. 安装相容性 `@docx-editor.dev/core` 与转换器相邻。 申请中保留一份核心副本.

## 安装软件包

```sh
npm install @docx-editor.dev/docx-to-pdf @docx-editor.dev/core
```

对于中文、日文或韩文文本,提供合适的字体或安装可选字体 `@docx-editor.dev/fonts-cjk` 软件包。 转换器在没有配置的情况下找到软件包.

如果您先前依赖捆绑的 CJK 覆盖, 请在您的生产依赖中添加可选的包 。 安装和部署详情见 [配置 PDF 字体](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/fonts.md)。 。 。 .

## 转换文档

```ts
import { readFile, writeFile } from 'node:fs/promises';
import { exportPdf } from '@docx-editor.dev/docx-to-pdf';

const source = await readFile('document.docx');
const result = await exportPdf(source, {
  displayMode: 'proposed',
  comments: true,
});

await writeFile('document.pdf', result.bytes);
```

转换保存源 DOCX. 浏览器应用程序必须将文档发送到Node.js服务器进行转换.

## 重新使用布局

使用 `openDocumentForExport` 财务报告和审定财务报表 `exportPdfFrom` 以重用字体分辨率和布局。 本会场还和马克当合作 `exportMarkdownFrom`。在所有出口,包括失败的出口之后处理会议。 例如,见 [比较 PDF 和 Markdown 转换](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/markdown-contract.md#reuse-one-session)。 。 。 .

## 配置输出

| 选项 | 默认 | 行为 |
| --- | --- | --- |
| `fidelityPolicy` | `'strict'` | 拒绝不支持或近似输出。 使用 `'best-effort'` 以诊断返回可用的输出. |
| `displayMode` | `'all-markup'` | 显示跟踪插入和删除。 使用 `'proposed'` 对案文的修改,包括接受的所有修改,或 `'original'` 用于原始内容. |
| `comments` | `true` | 包括本地PDF说明. 设定为 `false` 以略去它们. |
| `useSystemFonts` | `true` | 搜索支持字体文件的标准操作系统目录。 设定为 `false` 以禁用此搜索. |
| `timeoutMs` | `60000` | 设置以毫秒为单位的转换期限. |
| `maxOutputBytes` | `67108864` | 输出限制为64 MiB. 你可以降低这个限度. |
| `maxPages` | `10000` | 在布局后限制输出页面 。 你可以降低这个限度. |
| `signal` | —— 说 | 通过一个 `AbortSignal`。 。 。 . |

结果包括: `bytes`, (中文(简体) ), `pageCount`, (中文(简体) ), `layoutRevision`, (中文(简体) ), `displayMode`, (中文(简体) ), `fontResolution`, (中文(简体) ), `diagnostics`,以及 `timings`Timings报告用毫秒时间打开文件,铺出页码,绘画内容并编码PDF. 每个结果都拥有它的字节缓冲.

### 字体

使用 `fonts` 在安装和包装源之前提供字体源。 使用 `fallbackFonts` 以在已打包的字体后添加源。 出口商在使用通用代号来代替尚未解决的家族之前,还读取了嵌入字体. 使用 `lastResortFonts` 在嵌入字体之后,并在通用代用字之前.

`glyphFallbacks` 为缺少的格言指定一个已命令的字体列表。 默认内容包括符号,阿拉伯语,希伯来语,数学,和彩色的emoji. 它们也覆盖 CJK 文本当 `@docx-editor.dev/fonts-cjk` 已安装。 来自COLR字体的Emoji保留了它们的调色板颜色和可提取文本.

`fontPolicy` 控制字体源失败和家族覆盖. `fidelityPolicy: 'strict'` 拒绝可改变页化的通用替代. `fidelityPolicy: 'best-effort'` 使用这些替代品并报告。 检查 `result.fontResolution` 用于选择的面相和源失败.

关于可选倒置拒绝,见 [将字体策略与 PDF 策略分开](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/fonts.md#separate-font-policy-from-pdf-policy)。 。 。 .

关于自定义字体文件和政策选择,参见 [配置 PDF 字体](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/fonts.md)。 。 。 .

### 评论

评论成为范围重点或文字说明。 PDF观看者决定是否显示作者,日期,答复,以及解析状态. 跨页评论在每个受影响的页面上创建注释. 没有可见主播的评论会成为首页被标注的注释.

编辑 PDF 说明不会更新 DOCX .

## 支持的内容

-   可搜索多语言文本,小封盖,文本装饰,以及标签领导.
-   阿拉伯语加入跨格式运行和逻辑文本顺序,用于阿拉伯语,波斯语和希伯来语文本提取.
-   所选字体面部的合成粗体和斜体缺乏这些变体.
-   静态TrueType和CFF字体,包括从字体收藏中选取的面相.
-   页面大小、页框、页眉、页脚、脚注和尾注.
-   文本和图像列表标记、段落填充和段落边框.
-   表格文本、阴影和已解决的边框.
-   文本框和结构化等式.
-   支持向量形状,水平线和垂直线,以及保持其全宽的大纲.
-   PNG和JPEG的图像有裁剪,变相,α透明,以及固定不透明.
-   链接、目的地、文件元数据和评论.

即使DOCX元数据宣布另一种被支持的光栅格式,转换器也会读取PNG和JPEG图像. 得到支持的宣言包括巴布亚新几内亚、JPEG、GIF、BMP和WebP.

## 限制

转换器包括来自 `@docx-editor.dev/pro/drawing`,因此图表,绘图ML图,形状效果,VML文本路径,以及EMF和WMF图片渲染. 树图、日出和地图图, 以及将馅饼或雷达图与其他图型相结合的图, 不渲染。 这样的图表会输出它保存的回落图 。 否则,它被忽略了 `drawing` 诊断,因此默认的严格导出拒绝文档. 模块无法制取的绘图,旋转了表格-细胞文本,不支持等式回落,一些修订演示文稿,而其他不支持的媒体则会产生诊断. 不支持亮度和灰度调整 .

写作者拒绝可变字体,缺少格子,被禁嵌入,禁止子设定的字体,以及无法编码的字体容器. 不支持标记 PDF、PDF/A、加密和表格.

## 错误和资源限制

| 错误 | 原因 |
| --- | --- |
| `PdfDocumentOpenError` | Core拒绝了输入文件. 检查 `reason` 财务报告和审定财务报表 `detail`。 。 。 . |
| `PdfFidelityError` | 遇到不支持或大致内容的严格导出 。 检查 `diagnostics`。 。 。 . |
| `ExportResourceError` | 取消,截止日期,字体政策拒绝,或排版失败. 检查 `code`。 。 。 . |
| `PdfWorkLimitError` | 内容超过了处理限制. |
| `PdfOutputLimitError` | 编码字节已超过 `maxOutputBytes`检查 `limit` 财务报告和审定财务报表 `actual`扩展 `PdfEncodingError`。 。 。 . |
| `PdfPageLimitError` | 布局超过 `maxPages`检查 `limit` 财务报告和审定财务报表 `actual`扩展 `RangeError`。 。 。 . |
| `PdfEncodingError` | PDF 编码失败 。 检查 `cause`。 。 。 . |
| `TypeError` 或者说 `RangeError` | 参数无效或大小限制被超过 . |

作者会压缩内容流并嵌入字体子集. 它保留了排版记录和字体数据,直到转换完成. 核心的资源限度也适用.

在布局、油漆和编码批次之间检查取消。 同步字体和图像操作不能中断中调 。 对于硬期限或堆积限制,在工人中运行转换并配置 `resourceLimits.maxOldGenerationSizeMb`。 。 。 .

## 开发者指南

-   [比较 PDF 和 Markdown 转换](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/markdown-contract.md): 共享控制和有意差异.
-   [PDF 导出 API](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/api.md):选项,结果字段,诊断,稳定出错代码,以及资源边界.
-   [配置 PDF 字体](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/fonts.md):自定义文件,源指令,政策,以及故障排除.
-   [整合 PDF 转换](https://npmcn.com/package/%40docx-editor.dev/docx-to-pdf/docs/integrations.md): HTTP 响应,Next.js,部署,和分批.

## 运行演示

从寄存器根, 运行 :

```sh
bun install
bun run dev:pdf
```

打开 [http://127.0.0.1:5180 (中文(简体) )](http://127.0.0.1:5180/)。关于上传限制、服务器配置和生产命令,参见 [演示读取](https://npmcn.com/package/examples/docx-to-pdf/README.md)。 。 。 .

## 常见问题

### @docx-editor\.dev/docx-to-pdf 是什么？

在 Node\.js 上将 DOCX 转换为 PDF ,并带有可搜索的文本,嵌入字体和注释\.

### 如何安装 @docx-editor\.dev/docx-to-pdf？

在项目目录运行 npm install @docx-editor\.dev/docx-to-pdf，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@docx-editor\.dev/core（~2\.38\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @docx-editor\.dev/docx-to-pdf 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @docx-editor\.dev/docx-to-pdf 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @docx-editor\.dev/docx-to-pdf 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.16\.0 \|\| \>=22\.3\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @docx-editor\.dev/docx-to-pdf 可以商用吗？

@docx-editor\.dev/docx-to-pdf 使用 LicenseRef-EigenPal-Pro-Evaluation-1\.0 许可。声明的许可为 LicenseRef-EigenPal-Pro-Evaluation-1\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @docx-editor\.dev/docx-to-pdf 的下载量有多少？

根据 npm 官方下载统计，@docx-editor\.dev/docx-to-pdf 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,969 次，日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @docx-editor\.dev/docx-to-pdf 还在维护吗？

最新版本 2\.38\.0 发布于 2026/11/16（今天）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/09/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

