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

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

版本：2\.37\.0
npm 元数据更新时间：2026-11-11T10:30:47.546Z
中文译文更新时间：2026-11-12T14:29:11.974Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：211 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.16\.0 \|\| \>=22\.3\.0
- 运行依赖：2 个
- peer 依赖：@docx-editor\.dev/core ~2\.37\.0
- 首次发布：2026-09-15T14:52:24.961Z
- 最新版本发布：2026-11-11T10:30:46.942Z
- 近 30 天下载量：9273（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

将 DOCX 转换为 Markdown 并带有出自布局的页面,页眉,页脚,注释和跟踪的更改.

## 安装

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

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

## 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 到 马克当

使用 `@docx-editor.dev/docx-to-markdown` 将 DOCX 文件转换为 Markdown。 结果包括正文、页、页眉、页脚、评论和跟踪变化.

[尝试 DOCX 到 Markdown 演示](https://docx-to-markdown.docx-editor.dev/) 或读取 [标记下导出指南](https://www.docx-editor.dev/docs/2.x/export/markdown)。 。 。 .

## 在你开始之前

对于Node.js,在20x放行使用20.6.0版本或后期,或22.3.0版本或后期. 转换器需要WebAssembly并默认使用捆绑字体.

## 安装软件包

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

`@docx-editor.dev/core` 是一个必要的同伴依赖。 安装一个满足转换器对等依赖范围的版本,并输入您的锁定文件 .

## 转换 DOCX 文件

以下示例在Node.js读取一个本地文件:

```ts
import { readFile } from 'node:fs/promises';
import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';

const docxBytes = await readFile('document.docx');
const result = await exportMarkdown(docxBytes);
console.log(result.markdown);
```

## 包含图像

设定 `images: true` 以包含图像链接和提取字节 :

```ts
const result = await exportMarkdown(docxBytes, { images: true });
```

`result.media` 包含图像字节及其页面出错。 见 [图像工作流程](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/images.md) 以保存文件夹、下载 ZIP 或返回主机URL.

### 保存显示的图像大小

使用 `images: { syntax: 'html' }` 以生成时包含显示大小 `<img>` 标签。 尺寸使用整个 CSS 像素. 配置您的渲染器, 允许对 HTML 进行消毒并保留 `width` 财务报告和审定财务报表 `height`。默认的Markdown语法没有大小属性.

对于自定义预览,请使用 `displayWidthPx` 财务报告和审定财务报表 `displayHeightPx`资产 `pixelWidth` 财务报告和审定财务报表 `pixelHeight` 描述图像文件。 转换器会省略裁剪,自转,和浮动的文本包装. 见 [保存显示的图像大小](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/images.md#preserve-displayed-image-sizes)。 。 。 .

## 读取页面输出

文档布局引擎计算出分页符.

```ts
for (const page of result.pages) {
  console.log(page.number, page.markdown);
  console.log(page.headerMarkdown, page.footerMarkdown);
}
```

`result.markdown` 包含没有分页符的连续文档文本。 用于未页 `.md` 下载。 页眉和页脚留在里面 `result.pages`。 。 。 .

搜索和AI摄入,使用 `{ displayMode: 'proposed' }` 以显示待补插入并隐藏待补删除。 默认, `'all-markup'`,显示两者.

## 配置准确布局的字体

字体决定行环绕、表格行高和页边框 `result.pages`. Markdown并不保留DOCX字体家族,但转换器需要字体测量来计算布局.

从捆绑的通用文档字体的替代品开始。 使用 `fonts` 以提供作者许可的字体或覆盖替代字体。 使用 `fallbackFonts: googleFonts()` 从 Google Fonts 中装入缺失的面孔; 它需要网络访问, 并且不会覆盖先前来源已经解决的面孔 .

见 [字体设置和排除出错](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/fonts.md) 可运行实例、解析报告和源文档页面引用匹配指南.

## 运行时间和产出

对于Next.js,使用节点运行时间和 [服务器软件包配置](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/integrations.md#nextjs)。边缘运行时间不支持.

分页符取决于字体,文档特征,以及修订版模式;它们可以不同于创建文档的应用程序. 将文档版本与页面引用一起存储. `result.warnings` 报告省略了内容和字体问题。 除非启用, 图像会被省略 。 见 [产出限制](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/api.md#markdown-limitations) 在使用输出作为完整转录之前.

该软件包使用Apache 2.0许可证,包括评论和履带变化提取. 套装字体保留自己的开源许可证.

## 今后的步骤

-   [配置字体和解决问题的页面布局](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/fonts.md)。 。 。 .
-   [包含和传送图像](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/images.md)。 。 。 .
-   [连接转换器到您的应用程序](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/integrations.md)。 。 。 .
-   [审查出口选项和结果字段](https://npmcn.com/package/%40docx-editor.dev/docx-to-markdown/docs/api.md)。 。 。 .

## 常见问题

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

将 DOCX 转换为 Markdown 并带有出自布局的页面,页眉,页脚,注释和跟踪的更改\.

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

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

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

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

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

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

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

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

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

@docx-editor\.dev/docx-to-markdown 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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