# @bitplane/rars 中文文档

规范地址：https://npmcn.com/package/%40bitplane/rars/

版本：0\.12\.4
npm 元数据更新时间：2026-11-05T23:50:35.177Z
中文译文更新时间：2026-11-08T04:53:59.322Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：5.1 MB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-18T04:15:23.527Z
- 最新版本发布：2026-11-05T23:50:34.807Z
- 近 30 天下载量：3340（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

在浏览器和节点中读取,写作并修复RAR档案,没有本土依赖性.

## 安装

```sh
npm install @bitplane/rars
```

也可以使用：`pnpm add @bitplane/rars`、`yarn add @bitplane/rars`、`bun add @bitplane/rars`

## README

# @ bitplane/ rars (英语)

在浏览器和节点中读取,写入并修复RAR档案.

```sh
npm install @bitplane/rars
```

## 读取

```js
import { RarArchive } from "@bitplane/rars";

const archive = await RarArchive.open(file, { password: "optional" });

for (const entry of archive.entries) {
  console.log(entry.name, entry.size, entry.isEncrypted);
}

const bytes = await archive.get("docs/readme.txt").bytes();
await archive.test();
archive.close(); // optional; releases retained input eagerly
```

`open()` 接受一个 `Blob`, (中文(简体) ), `ArrayBuffer` 或输入数组。 通过命令阵列 打开一卷集。 条目对象内部使用存档顺序索引, 所以 重复名称和非UTF-8名称保持不变; `nameBytes` 包含 确切的标题字节.

`get(name)` 选择最后一个匹配条目; `getAll(name)` 返回每个匹配 在存档顺序。 每个返回的条目按指数读取自己的有效载荷.

节点也接受路径和文件 URL. 通过常规的第一条道路 音量集自动发现其兄弟姐妹.

对于遗产字节名称,通过 `legacyNameEncoding: "cp850"` 改为 `open()`。 。 。 . 支持的编码是 `cp437`, (中文(简体) ), `cp850`, (中文(简体) ), `cp852`, (中文(简体) ), `cp866`, (中文(简体) ), `windows-1251`, (中文(简体) ), `windows-1252` 财务报告和审定财务报表 `utf-8` (单位:千美元)`cp1251`, (中文(简体) ), `cp1252` 财务报告和审定财务报表 `utf8` 属于别名). 姓名为不敏感。 Unicode 名称优先; 未指定遗留 编码从未被猜出. 无效或未定义的输入失败转换 . `entry.name` 是选定的视图,并且 `entry.nameBytes` 保留原来的 身份证明 重新打开以选择另一个编码 . `get()` 拒绝模糊的解码 名称为 `AMBIGUOUS_ENTRY`; 使用 `getAll()` 或存档顺序条目索引. 此设置不影响注释,密码,有效载荷或写作名称.

`open()`, (中文(简体) ), `entry.bytes()`, (中文(简体) ), `readMany()`, (中文(简体) ), `test()` 财务报告和审定财务报表 `readComment()` 接受 `ReadOptions`数字 :

```js
const limits = { maxHeaderCount: 10000, maxMemberOutputBytes: 256 * 1024 * 1024 };
const archive = await RarArchive.open(file, limits);
const bytes = await archive.entries[0].bytes(limits);
const selected = await archive.readMany([archive.entries[1], archive.entries[0]], limits);
const comment = await archive.readComment(limits); // undefined if absent
```

可选字段是 `maxHeaderCount`, (中文(简体) ), `maxHeaderBytes`, (中文(简体) ), `maxMemberOutputBytes`, (中文(简体) ), `maxTotalOutputBytes`, (中文(简体) ), `maxReaderWorkspaceBytes`, (中文(简体) ), `rar50DictionarySizeLimit` 财务报告和审定财务报表 `rar50BufferedDecodeLimit`。数值必须是非负式安全整数或 `bigint` 数值通过 `2n ** 64n - 1n`零是一个真正的极限。 豁免保留 库默认值。 资源选项适用于一个呼叫,而不是由 `open()`。 。 。 . 每个操作重分出其输入;每个归档/音量都适用标题限制. `readMany()` 接受可移动的条目或名称并进行一个解析 批次的解码器转动。 结果保留请求顺序和重复; 偏好条目对象,用于复制身份和直接索引选择。 条目 从另一个档案被拒绝。 固体前身被解码一次,和 产出限制适用于整个批次。 重复的结果有独立的字节 缓冲,但不再使用逻辑解码配额 。 未返回部分 列表中选择一个选项。 Directories被否决;RAR5重定向器没有可读文件有效载荷. 缓存 `archive.comment` 被解码在转到的选项下 `open()`· ; `readComment()` 再次用新选项和可选密码解码.

输出限制数逻辑解码字节,包括已丢弃的固件前缀 输出。 读取一个音量条目目前解码整个音量集,所以 总产出限制包括其他成员。 限制不是聚合内存 上限:实现投入和返回的产出,以及解码工作空间 有单独的成本。 RAR5/7字典和缓冲解码限制影响这些 仅限格式。 文件系统抓取解码在WASM后端无法使用. 未知大小的 RAR5 成员在成员输出限制下被拒绝; 解码到端 支助仍然是单独的工作.

`maxReaderWorkspaceBytes` 限制每个调用的总读者分配能力, 包括解码器状态和排队的平行有效载荷。 源缓冲器, JavaScript 对象和返回的字节都在配额之外。 能力替换重叠 计数; 这不是进程内存限制 。 拒绝保留资源错误代码 和字节细节.

## 写入

```js
import { RarWriter } from "@bitplane/rars";

const writer = new RarWriter({ format: "rar50", level: 5 });
writer
  .add("hello.txt", "hello")
  .add("data.bin", payload, { mode: 0o644, modifiedAt: new Date() });

const bytes = await writer.bytes();
const parts = await writer.volumes(5 * 1024 * 1024);
```

`level` 从 0( 存储) 到 5 。 其他选项是: `solid`, (中文(简体) ), `password`, (中文(简体) ), `encryptHeaders`, (中文(简体) ), `comment` 财务报告和审定财务报表 `recoveryPercent`。节点额外提供 `addFile()`, (中文(简体) ), `writeTo()` 财务报告和审定财务报表 `writeVolumesTo()`。 。 。 . 关于遗留格式, `writeVolumesTo()` 稍后保留第一个路径和名称 数量 `.r00` 结束 `.r99` 在同一目录中。 超过101卷 或包含重叠输出路径,则在写入任何文件之前被拒绝.

长期业务接受 `AbortSignal` 和进度回调 :

```js
const bytes = await writer.bytes({
  signal: controller.signal,
  onProgress: ({ phase, completed, total }) => {
    console.log(phase, completed, total);
  },
});
```

错误是 `RarError` 有稳定状态的 `code`; 客户端 `AbortSignal` 取消使用标准 `AbortError`。核心错误通过密码 WASM和工人没有解析消息短信. `details.contexts` 保留 条目名称作为原始字节数组、操作、归档抵消和音量数字. 资源限制细节对字节数使用小数字符串,保存值 超过 JavaScript 的确切整数范围 。 使用节点文件系统错误 `IO` 与 原系统代码、错误和调用 `details`。 。 。 .

中止已排队的工作立即拒绝,而不中断活动 操作。 中止活体工作将终止工人的工作;以后开始作业 一个新鲜的工人。 这是工人解雇,所以它不经营合作的Rust 清除或撤销已完成的文件系统写入 。 断断续续的节点会离开 已启动临时文件。 联合来文中不需要单独的取消对象.

`RarWriter` 接受 `maxMemoryBytes` 作为非负式安全整数或 `bigint` 结束 `2n ** 64n - 1n`它限制管理RAR5/7执行分配能力, 包括保留的WASM spolls、存档/批量输出和最后的JavaScript 有效载荷副本。 默认是无限的;零承认没有管理下的分配. 拒绝有代码 `RESOURCE_LIMIT`; 遗留格式拒绝所请求的政策 与 `UNSUPPORTED_FEATURE`。调用器输入,返回调用器拥有的字节, JavaScript 运行时对象,分配器上方,堆栈和OS内存不包括在内. 这是 而不是一个过程-模拟天花板,并且不绑定读取或重写中转.

## 正在装入

ES模块,节点 `require`、Vite、网页包装、滚动和直接浏览器进口 相同的API,不需要明确的Wasm初始化:

```html
<script type="module">
  import { RarArchive } from "https://esm.sh/@bitplane/rars";
</script>
```

直接的跨原产地进口使用小块的工人靴子。 限制性 内容安全 因此,政策必须允许 `blob:` 内 `worker-src`,或 包件资产应从页面的出处捆绑或送达.

当前 API 实现输入和输出字节。 真实回压流 输入/产出将单独添加,而不是显示流 暗地里缓冲整个档案.

同一图书馆可供使用 [破烂箱子](https://crates.io/crates/rars), (中文(简体) ), [Python 软件包](https://pypi.org/project/rars/) 财务报告和审定财务报表 [命令行工具](https://github.com/bitplane/rars)。 。 。 .

## 开发验证

运行 `CARGO_BUILD_JOBS=1 scripts/build-npm.sh --debug` 接下来 `node scripts/test-npm-package.js` 用于重点发动机和工人检查. 调试构建跳过 LTO 和 `wasm-opt`。用 `scripts/build-npm.sh` 无 `--debug`。两种模式都要求 `wasm-bindgen` CLI 匹配 `Cargo.lock`。 。 。 .

## 发展覆盖面

从寄存器根运行 `python3 scripts/coverage-wasm.py` 计量 Rust引擎在节点下覆盖. 它需要节点, `wasm-bindgen` 匹配 `Cargo.lock`,并使用 LLVM 23与 `wasm32-unknown-unknown` 财务报告和审定财务报表 `llvm-tools-preview` 已安装。 命令使用一个构建任务,最多 两个可用的CPU, 并保存被忽略的报表 `target/coverage-wasm-focused` 目录.

一个独立的两分支探测器在测试前检查测量 发动机。 私有错误转换测试被编译为 `cfg(test)`· ; 其出口量和图解运行时间积分都不存在. 此测量 Rust WASM 源,与 JavaScript 外观覆盖分开.

## 常见问题

### @bitplane/rars 是什么？

在浏览器和节点中读取,写作并修复RAR档案,没有本土依赖性\.

### 如何安装 @bitplane/rars？

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

### @bitplane/rars 支持 TypeScript 吗？

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

### @bitplane/rars 支持 ESM 还是 CommonJS？

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

### @bitplane/rars 需要什么版本的 Node\.js？

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

### @bitplane/rars 可以商用吗？

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

### @bitplane/rars 的下载量有多少？

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

### @bitplane/rars 还在维护吗？

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