# @giraffesyo/downmark 中文文档

规范地址：https://npmcn.com/package/%40giraffesyo/downmark/

版本：0\.10\.1
npm 元数据更新时间：2026-10-21T18:36:29.049Z
中文译文更新时间：2026-11-16T09:51:36.212Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40giraffesyo/downmark
原文对照：https://npmcn.com/package/%40giraffesyo/downmark/?lang=original
项目主页：https://github.com/giraffesyo/downmark#readme
源码仓库：https://github.com/giraffesyo/downmark

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

- 包体积（解压后）：12.8 MB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-18T20:31:08.822Z
- 最新版本发布：2026-10-21T18:36:28.671Z
- 近 30 天下载量：2933（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

将 PDF, DOC, DOCX, XLSX, PPTX, HTML, CSV, ZIP, 和纯文本文档转换为Markdown. 纯WebAssembly;在节点和浏览器中运行,依赖度为零.

## 安装

```sh
npm install @giraffesyo/downmark
```

也可以使用：`pnpm add @giraffesyo/downmark`、`yarn add @giraffesyo/downmark`、`bun add @giraffesyo/downmark`

## README

# @giraffesyo/ 下标记

在Node.js和浏览器中将文档转换为Markdown:PDF,DOCX,XLSX,PPTX,DOC(Word 97–2003),HTML,CSV,ZIP档案,和Plaintext. 这是纯粹的去 [下标记](https://github.com/giraffesyo/downmark) 库,用一个小的 TypeScript API 包裹。 一切都在当地运行,没有网络呼叫.

## 安装

```sh
npm install @giraffesyo/downmark
```

需要18号节点或任何现代浏览器.

## 两次执行,一次API

`convert()` 运行相同的 Go 代码 无论是哪种方式, 但有两个建筑它 和包之间选择每个主机 :

-   **本地二进制**,每平面包件内装船 (单位:千美元)`@giraffesyo/downmark-linux-x64` 5个兄弟姐妹) 宣布为可选依赖。 npm 只安装一个匹配 主办单位 `os`编号 :`cpu` 并跳过其余。 没有下载步骤也没有 邮购脚本: 二进制在柏油球内,所以 `npm install` 在一个代理 和一个空中集束, `pnpm deploy` 携带 锁被钉住.
-   **网络大会建设**,捆绑在这个包中,在没有的情况下使用 应用平台软件包——浏览器,未列出的平台,安装器 运行与 `--omit=optional`。 。 。 .

他们也一样回来 `{ markdown, title, warnings }` 对于相同的输入。 这个 本地路径更快, 运行转换到另一个进程而不是打开 事件循环,是唯一可以做到的 [OCR (英语)](https://npmcn.com/package/%40giraffesyo/downmark/#readme-ocr-for-scanned-pdfs)。 。 。 . 没有其他关于你的代码改变.

```js
import { binaryPath } from "@giraffesyo/downmark";

binaryPath(); // "/…/node_modules/@giraffesyo/downmark-darwin-arm64/bin/downmark", or null on wasm
```

所支持的平台:linux,darwin,并使用x64和arm64的win32. 前进 二进制是静态的,所以Linux包覆盖了glibc和musl(高山) 一样.

设定 `DOWNMARK_FORCE_WASM=1`,或打电话 `init({ preferWasm: true })`,忽略 一个已安装的二进制——用于比较两者. `DOWNMARK_BIN=/path/to/downmark` 在您自己的二进制中点出; 如果不存在, 调用比方 而不是悄悄地掉下来.

## 用法(节点)

```js
import { readFile } from "node:fs/promises";
import { convert } from "@giraffesyo/downmark";

const data = await readFile("report.docx");
const { markdown, title } = await convert(data, { filename: "report.docx" });
console.log(markdown);
```

通用JS同样工作:

```js
const { convert } = require("@giraffesyo/downmark");
```

在原生路径上,每次转换都产出二进制(约5-10 ms of ),而没有任何内容被载入您的进程。 在原地的道路上 模块在第一次呼叫时被懒散地装入并被缓存,所以随后 调用重复使用同一实例.

## 用法 (浏览器)

```js
import { convert } from "@giraffesyo/downmark";

const file = input.files[0];
const data = new Uint8Array(await file.arrayBuffer());
const { markdown } = await convert(data, { filename: file.name });
```

浏览器没有产入过程,所以这总是被堆积而成.

浏览器构建抓取 `downmark.wasm` 相对于通过 `new URL("./downmark.wasm", import.meta.url)`. Bundlers 了解该模式的 (Vite, Webpack 5, Rollup with the url 插件) 自动将被体复制到构建输出中.

如果你的捆绑者不这样做,指 `init()` 在第一次通话前

```js
// Vite
import wasmUrl from "@giraffesyo/downmark/downmark.wasm?url";
import { init, convert } from "@giraffesyo/downmark";

await init(wasmUrl);
```

`init()` 接受字符串 URL/ path, a `URL`,一个 `ArrayBuffer`编号 :`Uint8Array`页:1 `Response`,或预编译 `WebAssembly.Module`。 。 。 .

没有捆绑? 见 [`example/browser.html`](https://github.com/giraffesyo/downmark/blob/canary/js/example/browser.html) 为平地 `<script type="module">` 页 次.

**服务提示 :** 原为~12 MB 未压缩。 给它服务 `Content-Encoding: br` 或者说 `gzip` (≈-4-6 MB过线)和a `Content-Type: application/wasm` 标题如此 `WebAssembly.instantiateStreaming` 踢入( 如果MIME 类型错误, 包会回到缓冲) .

## API 密码

### `convert(data, options?) → Promise<{ markdown, title, warnings }>`

`data` 是一个 `Uint8Array` 或者说 `ArrayBuffer`。所有选项都是可选的,但您给出的提示越多,格式检测就越好:

| 选项 | 类型 | 含义 |
| --- | --- | --- |
| `filename` | `string` | 源文件的基名,例如:. `"report.docx"` |
| `mimeType` | `string` | 无参数的媒体类型,例如:. `"application/pdf"` |
| `extension` | `string` | 文件扩展名( 正常化为小写并带有前缀) |
| `charset` | `string` | IANA 字符集名称用于文本输入, 例如 . `"shift_jis"` |
| `keepDataUris` | `boolean` | 饱满 `data:` URIs (HTML) / 嵌入图像作为数据 URIs (DOCX) |
| `resultLimit` | `number` | 拒绝大于此数字节的结果 `RESULT_TOO_LARGE` |
| `ocr` | `object` | 使用 OCR 引擎读取扫描的 PDF 页面([下级](https://npmcn.com/package/%40giraffesyo/downmark/#readme-ocr-for-scanned-pdfs); 仅本地二进制 |

`warnings` 报告转换损失,当转换损失时为空 没什么 返回警告的转换仍然成功——Markdown是 有用,但并不是所有的输入.

```js
const { markdown, warnings } = await convert(data, { filename: "scan.pdf" });
for (const w of warnings) {
  // { converter: "pdf", code: "incomplete", location: "page 12", message: "..." }
  console.warn(`${w.code}: ${w.message}`);
}
```

`code` 无论是 `"incomplete"` (所持有的输入内容在 产出)或 `"skipped"` (整个单位从未尝试).

### 扫描的 PDF OCR

被扫描的页面持有图像,而不是文本,所以从 他们。 过 `ocr` 将这些页面交给OCR引擎:

```js
const { markdown } = await convert(data, {
  filename: "scan.pdf",
  ocr: { engine: "tesseract", lang: "eng", maxPages: 30 },
});
```

| 外地 | 类型 | 含义 |
| --- | --- | --- |
| `engine` | `"tesseract"` | 要求。 要运行的引擎; 必须安装 |
| `bin` | `string` | 运行此可执行文件而不是打开 `PATH` |
| `lang` | `string` | 语法中的语言,例如:. `"eng"` 或者说 `"eng+deu"` |
| `minConfidence` | `number` | 将单词从此下移, 在 Tesseract 的 0- 100 比例上 |
| `policy` | `"textless"` | `"thin"` | `"images"` | 没有自己文本的页面( 默认) , 也可以在打字头下扫描, 或者每页画一幅图像 |
| `minGlyphs` | `number` | 与 `policy: "thin"`,一个页面需要算作排字; `50` 默认 |
| `maxPages` | `number` | 每个文件最多有这么多页的OCR; `0` 无限制 |
| `pageTimeoutMs` | `number` | 这么长时间后放弃一页 |
| `timeoutMs` | `number` | 这么长时间之后 放弃整个文件的OCR |

页面可以是扫描而不带文本:传真或签名表格 搭载打字头——日期戳,出行行,页码—— 在身体的一幅图上 单独取出那个头像. `policy: "thin"` 也读这些,将任何页面交给引擎 少于 `minGlyphs` 画出图像的格言,同时留下页 仅用自己的文本层. `policy: "images"` 读取每一页 绘制图像,包括类型文档中的数字.

没有 OCR 引擎 : `engine: "tesseract"` 运行 a [语法](https://github.com/tesseract-ocr/tesseract) 您已安装 你自己来 OCR大约每页花费一秒钟, 这就是为什么它关闭,除非 问及预算为何存在.

填入的页面 OCR 在 Markdown 中标出 HTML 注释 (单位:千美元)`<!-- downmark: page 1 includes OCR text -->`:OCR文本是读取 墨水而不是文档本身的字符, 以及不能 告诉两者不能有不同的重量.

这需要本地的二进制——dem不能执行一个程序. 没有 已安装, 已通过 `ocr` 拒绝方式 `NATIVE_REQUIRED` 而不是说 返回时会悄悄地丢失其扫描页.

### `binaryPath() → string | null`

下一个本地二进制 `convert()` 会运行,或 `null` 当此主机 滚回原地去 对于更愿意执行CLI的来电者 他们自己接受 `-json` 并写入此软件包中相同的对象 返回.

### `canConvert(hints) → Promise<boolean>`

格式特定转换器是否声称提示所描述的格式(仅从提示判断,没有内容嗅取). `false` 这并不意味着 `convert()` 必须失败;它可能仍然会按其字节对输入进行分类,或者返回到纯文本中.

### `init(source?) → Promise<void>`

可选性,关于只执行问题. `convert()`编号 :`canConvert()` 默认初始化; 调用 `init()` 以覆盖原点 (见上面的 " 捆绑方 " ),在这种情况下,它必须在第一次谈判之前运行 转换。 在一个使用本地二进制的主机上,没有什么需要它.

它也接受一个选项对象:

```js
await init({ wasm: wasmUrl, preferWasm: true });
```

`preferWasm: true` 使每一个转换都使用相机,即使有一个平台 软件包已安装.

### `version() → Promise<string>`

下印版的被子从.

`canConvert()` 财务报告和审定财务报表 `version()` 从原地回答,即使当地人 安装了二进制, 并支付加载费 。 一个在本土路上的呼叫者 两者都不能跳过: `convert()` 分类输入本身, 财务报告和审定财务报表 `binaryPath()` 命名一个回答的二进制 `-version`。 。 。 .

### 错误

所有失败均以 `DownmarkError` 携带 `code`数字 :

| 代码 | 含义 |
| --- | --- |
| `UNSUPPORTED_FORMAT` | 没有转换器接受任何解释下的输入 |
| `INPUT_TOO_LARGE` | 转换器的硬输入预算被突破 |
| `RESULT_TOO_LARGE` | 超过结果 `resultLimit` |
| `CONVERSION_FAILED` | 转换器接受输入, 但每次尝试都失败 |
| `NATIVE_REQUIRED` | 呼叫需要本地二进制, 而这个主机没有 |
| `INTERNAL` | 错误的参数或出乎意料的内部失败 |

`CONVERSION_FAILED` 拒绝是 `ConversionFailedError` 实例 `attempts` 数组列出每个尝试过的转换器及其失败的原因 :

```js
import { convert, ConversionFailedError } from "@giraffesyo/downmark";

try {
  await convert(data, { filename: "broken.pdf" });
} catch (err) {
  if (err instanceof ConversionFailedError) {
    for (const a of err.attempts) console.error(`${a.converter}: ${a.message}`);
  }
}
```

## 说明和限制

-   **在tham上,转换为CPU绑定并被单行读取.** 一个大的PDF屏蔽了它运行的线程,所以在一个浏览器UI中,在一个Web Worker内部运行转换,以保持页面的响应. 没有 `timeout` 选项,因为忙碌的原案例不能被预先阻止。 原生路径没有这个问题:工作发生在另一个过程中,事件循环保持自由.
-   **非常大的 XLSX 部件 :** 包含大于 16 MiB 的单个内部部件的工作簿会触发 Excel 库的溢出到磁盘路径, 它在 ism( 没有文件系统) 上失败 。 此类文件以 `CONVERSION_FAILED`。 。 。 .
-   原物实例按进程/页数共享。 转换可以同时发布,但一次执行一次. 原生转化是独立的过程,确实平行运行.
-   **平台软件包是一个执行细节.** 取决于 `@giraffesyo/downmark`从来没有 `@giraffesyo/downmark-<platform>` 直接说.

## 发展

从 repo 根所建 :

```sh
make js-test   # build wasm + TS + the binary, run the Node test suite
```

`make wasm` 编译 `wasm/main.go` 改为 `js/dist/downmark.wasm` 刷新时 `js/vendor/wasm_exec.js` 从本地的Go工具链. `make js-bin` 正在建设 `cmd/downmark` 输入 `js/.bin`,这是本地测试的结果;没有它,他们跳过.

平台套件在发布时间构建,没有承诺:

```sh
goreleaser build --snapshot --clean            # dist/downmark_<goos>_<goarch>*/
node js/scripts/stage-npm-release.mjs --version 1.2.3
```

写着 `js/npm/<platform>/` 从这些二进制和邮票的版本 和六个 `optionalDependencies` 输入 `js/package.json`。依赖关系 产生而不是承诺,因为 `npm ci` 验证 `package.json` 以锁定文件为对象, 并发布名称版本 ——所以每一个干净的安装都会失败. 也没有 产出意在承付; `.github/scripts/check-npm-packages.sh` 在CI中运行相同的脚本来保持它诚实.

## 常见问题

### @giraffesyo/downmark 是什么？

将 PDF, DOC, DOCX, XLSX, PPTX, HTML, CSV, ZIP, 和纯文本文档转换为Markdown\. 纯WebAssembly;在节点和浏览器中运行,依赖度为零\.

### 如何安装 @giraffesyo/downmark？

在项目目录运行 npm install @giraffesyo/downmark，或使用 pnpm add / yarn add / bun add。

### @giraffesyo/downmark 支持 TypeScript 吗？

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

### @giraffesyo/downmark 支持 ESM 还是 CommonJS？

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

### @giraffesyo/downmark 需要什么版本的 Node\.js？

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

### @giraffesyo/downmark 可以商用吗？

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

### @giraffesyo/downmark 的下载量有多少？

根据 npm 官方下载统计，@giraffesyo/downmark 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,933 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @giraffesyo/downmark 还在维护吗？

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

