# @drupflare/untarl 中文文档

规范地址：https://npmcn.com/package/%40drupflare/untarl/

版本：0\.1\.1
npm 元数据更新时间：2026-11-13T06:48:40.571Z
中文译文更新时间：2026-11-13T06:50:53.597Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：22.2 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-13T23:27:07.102Z
- 最新版本发布：2026-11-13T06:48:40.197Z
- 近 30 天下载量：2361（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

无依赖性,工人安全焦油和焦油.gz提取. 节点APIs.

## 安装

```sh
npm install @drupflare/untarl
```

也可以使用：`pnpm add @drupflare/untarl`、`yarn add @drupflare/untarl`、`bun add @drupflare/untarl`

## README

# 解脱

> Tar和tar.gz 提取无依赖和无节点 API

[![Build](https://github.com/drupflare/untarl/actions/workflows/build.yml/badge.svg)](https://github.com/drupflare/untarl/actions/workflows/build.yml) [![Prettier](https://github.com/drupflare/untarl/actions/workflows/prettier.yml/badge.svg)](https://github.com/drupflare/untarl/actions/workflows/prettier.yml) [![codecov](https://codecov.io/gh/drupflare/untarl/branch/master/graph/badge.svg)](https://codecov.io/gh/drupflare/untarl) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40drupflare/untarl/LICENSE)

**读取 a `.tar` 或者说 `.tar.gz` 在工作,浏览器, 在 Bun 和 在节点, 相同 代码和零依赖.** Gzip 由平台自己处理 `DecompressionStream('gzip')` 而不是一个捆绑的充气器,这就是保持 依赖数为零,捆绑成本为零.

* * *

## 目录

-   [为什么](https://npmcn.com/package/%40drupflare/untarl/#readme--why)
-   [安装](https://npmcn.com/package/%40drupflare/untarl/#readme--install)
-   [使用量](https://npmcn.com/package/%40drupflare/untarl/#readme--usage)
-   [API 密码](https://npmcn.com/package/%40drupflare/untarl/#readme--api)
-   [未信任的输入](https://npmcn.com/package/%40drupflare/untarl/#readme--untrusted-input)
-   [范围外](https://npmcn.com/package/%40drupflare/untarl/#readme--out-of-scope)
-   [测试](https://npmcn.com/package/%40drupflare/untarl/#readme--testing)
-   [相关仓库](https://npmcn.com/package/%40drupflare/untarl/#readme--related-repositories)
-   [许可证](https://npmcn.com/package/%40drupflare/untarl/#readme--license)

* * *

## 为什么

最初的问题是在运行时安装 Drupal 缩写模块,这意味着读取 drupal.org (英语) `.tar.gz` 从云旗工人里面 两个明显的答案都结束了:

1.  **在PHP中进行.** 原创建筑也没有 `ext-zip` 也没有 `ext-phar`,添加其中之一为 多小时 Docker 重建翻译.
2.  **使用焦油库.** 每一个受欢迎的 `node:zlib`, (中文(简体) ), `node:fs` 或者说 `Buffer`。 。 。 . 工人没有这些.

工人确实有 `DecompressionStream('gzip')`土生土长的 沥青只是 512字节块并有八进制头. 所以整个工作都适合 ~320行的平台 JavaScript, 出处 `await` 合法,没有建造旗帜必须改变.

* * *

## QQ 安装

```sh
bun add @drupflare/untarl
```

**一个入口.** 这个 `exports` 地图声明 `.` 财务报告和审定财务报表 `./package.json` 什么都没有 所以每个符号都来自 `@drupflare/untarl` 财务报告和审定财务报表 `@drupflare/untarl/src/untar.ts` 被拒绝 以判决者盟誓, 唯一一个模块的第二个名字是两种方式,可以导入同样的东西,没有 如何说哪一个是犬; 兄弟姐妹 `cartridge` 由子路径分割,因为它的模块有 不同抚养费用,这里没有什么不同.

* * *

## 使用量

常见的情况是两个调用:充气和分解,然后平分要写的文件.

```ts
import { tarEntryTree, untarGzip } from '@drupflare/untarl';

const response = await fetch('https://ftp.drupal.org/files/projects/token-8.x-1.15.tar.gz');
const entries = await untarGzip(response.body!);

// strip = 1 drops the `token/` wrapper every drupal.org tarball has
for (const [path, bytes] of tarEntryTree(entries, 1)) {
  // write `bytes` to `path` here
}
```

如果您已经持有字节, 或者归档没有被 gzip, 请直接跳到解析器 :

```ts
import { parseTar } from '@drupflare/untarl';

const entries = parseTar(new Uint8Array(await file.arrayBuffer()));
const names = entries.filter((e) => e.type === 'file').map((e) => e.name);
```

* * *

## • API

| 导出 | 签署 | 它会做什么 |
| --- | --- | --- |
| `untarGzip(stream)` | `(ReadableStream<Uint8Array>) => Promise<TarEntry[]>` | 枪口穿过 `DecompressionStream`,然后解析 |
| `parseTar(bytes)` | `(Uint8Array) => TarEntry[]` | 忠实地解析 POSIX/ ustar 归档; 以路径为由拒绝任何内容 |
| `tarEntryTree(entries, strip= 1)` | `(TarEntry[], number) => Map<string, Uint8Array>` | 平整要写的文件, 拒绝逃跑的路径 |
| `TarEntry` | `{ name, size, type, mode, bytes }` | 1名成员; `bytes` 是一个自有副本,所以可以发布归档 |
| `TarEntryType` | `'file' | 'directory'` | 数个打字板,意思相同,叠在一起 |
| `TarParseError` | `Error & { offset?: number }` | 畸形、截断或异地归档 |
| `TarPathError` | `Error & { path: string }` | 摆脱目标目录的成员路径 |

**两个出错类型之间的分出是设计.** `parseTar()` 忠实于字节 并很乐意将一个名字从目标目录中爬出 `..` 部分. `tarEntryTree()` 决定什么是安全的, 是扔出的唯一一层 `TarPathError`分离后,您可以检查一个敌对的档案 而不分析 内容.

* * *

## 未信任输入

网络上的焦油球是不信任的, 所以每个读取被限制 每一个失败都是 **名称** 错误而不是读取过缓冲器的末端, 无限回路, 或可能 空结果 .

| 拒绝 | 错误 |
| --- | --- |
| 短短的下载剪接标题 | `TarParseError`页:1 |
| (单位:千美元) `size` 超过缓冲的字段 | `TarParseError` |
| a 非绝对值 `size` 或者说 `mode` | `TarParseError` |
| 无名条目 | `TarParseError` |
| 绝对成员路径 | `TarPathError`从 `tarEntryTree()` |
| 包含 `..` | `TarPathError`从 `tarEntryTree()` |
| 敌对者 **目录** 名称,尽管已删除 | `TarPathError`: 在类型过滤器前选中 |
| 负或非整数 `strip` | `RangeError` |

**页:1.** 作者对是否 字段将字节合并为签名或未签名,因此执行时拒绝真实的档案; 八进制 并限制检查已经阻止了错误的页眉被读取。 这是决定,不是 遗漏.

* * *

## \* 超出范围

-   **它不流 剖析.** 归档是缓冲的,因为焦油头没有 后指: 不走之前的每个街区都找不到条目 。 用来画画 模块是几兆字节,这是它所构建的大小.
-   **它没有跟随链接.** 连线,硬链接和设备节点被消耗并投放. 模块安装中的任何内容都不应该跟随一个模块.
-   **它不写文件 .** `tarEntryTree()` 给你一个 `Map`那些字节的土地就是你的.
-   **它不创建档案.** 仅取出.

它能处理真正的 Drupal.org tarballs 中的形状: ustar `prefix` 拆分, GNU `L` 长 名称、 pax `x`编号 :`g` 页: 1 `x` 标题 `path=` 记录重命名其条目 描述),和 v7 将目录写作打字旗的习惯 `0` 带着一刀一刀.

* * *

## 测试

```sh
bun run typecheck
bun run test # 89 assertions across 2 specs
bun run test:coverage
```

**89个通过**时 **98.68%的报表**, 超过所建档案而非登录 所以上面的每个拒绝 都有一个案件会影响它.

两行被揭出. `src/untar.ts:75` 这是 `byteAt()` 防线。 每个读头都坐着 在块内,循环已经检查过,所以无法从 `parseTar()`。 。 。 . `src/untar.ts:214` 是"不推进"的警卫, 这可以证明是无法到达的: `next` 实值 `headerAt + 512 + ceil(size / 512) * 512`这样 `next <= headerAt` 当一个信头是 整个街区。 因为它防止的失败是绞刑而不是错误.

* * *

## 有关仓库

| 仓库 | 这是什么 |
| --- | --- |
| [`drupflare/worker`](https://github.com/drupflare/worker) | 消费者: " Cloudflare Workers " 上的 " Drupal 11 " ,读取模块焦油丸 |
| [`drupflare/cartridge`](https://github.com/drupflare/cartridge) | 在持久对象中运行被屏蔽解释器的主机侧面 |
| [`drupflare/durabledb`](https://github.com/drupflare/durabledb) | 持久对象SQLite的测量极限,加上它们存活下来的编码器 |

* * *

## 许可证

MIT (c) 格雷戈里·米切尔 2026. 见 [自由主义](https://npmcn.com/package/%40drupflare/untarl/LICENSE)。 。 。 .

## 常见问题

### @drupflare/untarl 是什么？

无依赖性,工人安全焦油和焦油\.gz提取\. 节点APIs\.

### 如何安装 @drupflare/untarl？

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

### @drupflare/untarl 支持 TypeScript 吗？

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

### @drupflare/untarl 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @drupflare/untarl 可以商用吗？

@drupflare/untarl 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @drupflare/untarl 的下载量有多少？

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

### @drupflare/untarl 还在维护吗？

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