# @harvard-lil/js-wacz 中文文档

规范地址：https://npmcn.com/package/%40harvard-lil/js-wacz/

版本：0\.2\.0
npm 元数据更新时间：2026-10-23T18:03:56.457Z
中文译文更新时间：2026-11-17T12:47:26.592Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：63.7 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：12 个
- 首次发布：2023-02-23T22:06:10.464Z
- 最新版本发布：2026-09-10T16:29:54.541Z
- 近 30 天下载量：7356（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 1 个）

## 中文简介

JavaScript模块和CLI工具,用于使用WACZ格式规格处理网络存档数据.

## 安装

```sh
npm install @harvard-lil/js-wacz
```

也可以使用：`pnpm add @harvard-lil/js-wacz`、`yarn add @harvard-lil/js-wacz`、`bun add @harvard-lil/js-wacz`

## README

# 兹-瓦兹

[![Tests](https://github.com/harvard-lil/js-wacz/actions/workflows/test.yml/badge.svg)](https://github.com/harvard-lil/js-wacz/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/@harvard-lil/js-wacz)](https://www.npmjs.com/package/@harvard-lil/js-wacz) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com/)

JavaScript 模块和 CLI 工具,用于使用网络归档数据 [wACZ 格式规格](https://specs.webrecorder.net/wacz/1.1.1/),类似于 [网络录音器的 py -wacz](https://github.com/webrecorder/py-wacz)。 。 。 .

它可用于组合一组 `.warc` 编号 : `.warc.gz` 文件为单个 `.wacz` 文件 :

**在方案方面(节点:**

```javascript
import { WACZ } from '@harvard-lil/js-wacz'

const archive = new WACZ({ 
  input: 'collection/*.warc.gz', 
  output: 'collection.wacz',
})

await archive.process() // "my-collection.wacz" is ready!
```

**...或通过命令行:**

```bash
js-wacz create -f "collection/*.warc.gz" -o "collection.wacz"
```

**兹-瓦兹** 利用工人来平行处理尽可能多的WAC文件,像主机所能处理的那样.

[![Perma Tools](https://github.com/harvard-lil/tools.perma.cc/blob/main/perma-tools.png?raw=1)](https://tools.perma.cc/)

* * *

## 内容提要

-   [安装](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-install)
-   [CLI: 爱丽丝 `create` 命令](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-cli-create-command)
-   [程序使用](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-programmatic-use)
-   [与 py-wacz 的特征均等](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-feature-parity-with-py-wacz)
-   [发展](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-development)
-   [发布注释](https://npmcn.com/package/%40harvard-lil/js-wacz/CHANGELOG.md)

* * *

## 安装

**兹-瓦兹** 需求 [联合来文20+](https://nodejs.org/en/)。 。 。 .

`npm` 可用于安装此软件包并制作 **兹-瓦兹** 整个系统可访问命令 :

```bash
npm install -g @harvard-lil/js-wacz
```

[\* 回到摘要](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-summary)

* * *

## CLI: 爱丽丝 `create` 命令

这个 `create` 命令帮助组合一个或多个 `.warc` 或者说 `.warc.gz` 文件为单个 `.wacz` 文档.

```bash
js-wacz create -f "collection/*.warc.gz" -o "collection.wacz"
```

**兹-瓦兹** 接受下列选项和参数,用于自定义WACZ文件的组装方式.

### \--f 文档

这是唯一的 **所需经费** 参数,用于表示应当处理哪些文件并添加到产生的WACZ文件中.

目标可以是单个文件,也可以是诸如: `folder/*.warc.gz`。 。 。 .

```bash
# Single file:
js-wacz create --file archive.warc
```

```bash
# Collection:
js-wacz create --file "collection/*.warc"
```

**说明:** 在使用克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来克来.

### 产出

指定结果 `.wacz` 文件应该创建,其文件名应该是什么.

默认为 `archive.wacz` 如果不提供,则在当前目录中.

完成的档案只有在成功完成后才取代现有的目的地。 处理错误保存上一个文件并删除临时输出.

```bash
js-wacz create --file cool-beans.warc --output cool-beans.wacz
```

### \-- --pages --p

文件夹的路径 [页: 1](https://specs.webrecorder.net/wacz/1.1.1/#pages-jsonl) 文档(`pages.jsonl`, (中文(简体) ), `extraPages.jsonl` (......) (中文(简体) ).

如果没有提供, **兹-瓦兹** 试图检测WARC记录中的页面以构建自己的 `pages.jsonl` 指数.

```bash
# Assuming the following file exists: /collections/pages/pages.jsonl
js-wacz create -f "collection/*.warc.gz" --pages collection/pages/
```

### \--cdxj (中文(简体) )

传递已存在的 CDXJ 文件目录,而不是从 WARCs 中索引 。 必须结合使用 `--pages`。 。 。 .

```bash
js-wacz create -f "collection/*.warc.gz" --pages collection/pages.jsonl --cdxj collection/indexes/
```

### \- url (英语)

如果提供,将用作 [`mainPageUrl` 属性 `datapackage.json`](https://specs.webrecorder.net/wacz/1.1.1/#datapackage-json)。 。 。 .

必须是有效的 URL .

```bash
js-wacz create -f "collection/*.warc.gz" --url "https://lil.law.harvard.edu"
```

### \--ts 时

如果提供,将用作 [`mainPageDate` 属性 `datapackage.json`](https://specs.webrecorder.net/wacz/1.1.1/#datapackage-json)。 。 。 .

可以是任何值 [由 JavaScript 解析 `Date() constructor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)。 。 。 .

```bash
js-wacz create -f "collection/*.warc.gz" --ts "2023-02-22T12:00:00.000Z"
```

### 标题

如果提供,将用作 [`title` 属性 `datapackage.json`](https://specs.webrecorder.net/wacz/1.1.1/#datapackage-json)。 。 。 .

```bash
js-wacz create -f "collection/*.warc.gz" --title "My collection."
```

### \--desc 数据

如果提供,将用作 [`description` 属性 `datapackage.json`](https://specs.webrecorder.net/wacz/1.1.1/#datapackage-json)。 。 。 .

```bash
js-wacz create -f "collection/*.warc.gz" --desc "My cool collection of web archives."
```

### \-- 正在签名- url

如果提供,将用作应用的API终点 [生成的 WACZ 文件的加密签名](https://specs.webrecorder.net/wacz-auth/0.1.0/)。 。 。 .

这个终点预计将是: [与符号兼容](https://github.com/webrecorder/authsign)。 。 。 .

签名 URL 无效或签名检查失败拒绝导出 。 返回的散列必须与根表相匹配,其签名必须与所提供的密钥或域证书相验证. 此检查不验证证书信任度,域名,或RFC 3161倍戳. 见 [发布注释](https://npmcn.com/package/%40harvard-lil/js-wacz/CHANGELOG.md) 用于支持的格式和历史散列兼容性.

```bash
js-wacz create -f "collection/*.warc.gz" --signing-url "https://example.com/sign"
```

### \-- 正在签名

与 `--signing-url` 如果提供,如果签名服务器需要认证.

```bash
js-wacz create -f "collection/*.warc.gz" --signing-url "https://example.com/sign" --signing-token "FOO-BAR"
```

### \--log级

可用于确定动词 **兹-瓦兹** 需要这样.

-   可能的值是: `silent`, (中文(简体) ), `trace`, (中文(简体) ), `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`
-   默认是: `info`

```bash
js-wacz create -f "collection/*.warc.gz" --log-level trace
```

### \- 日志目录 - l

包含日志文件的文件夹路径( WACZ 中只包含有.log或.txt文件扩展名的文件) .

```bash
# Assuming the following file exists: collection/logs/crawl.log
js-wacz create -f "collection/*.warc.gz" --log-directory collection/logs/
```

[\* 回到摘要](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-summary)

* * *

## 程序使用

**兹-瓦兹**'CLI和基础逻辑脱钩,因此可以作为JavaScript模块被消耗 _(目前仅与Node.js)_。 。 。 .

**实例:在方案上创建一个已签名的WACZ**

```javascript
import { WACZ } from '@harvard-lil/js-wacz'

try {
  const archive = new WACZ({ 
    input: 'collection/*.warc.gz',
    output: 'collection.wacz',
    signingUrl: 'https://example.com/sign',
    signingToken: 'FOO-BAR',
  })

  await archive.process()

  // collection.wacz is ready
} catch(err) {
  // ...
}
```

虽然a `process()` 提供了方便方法,所述程序的每一个步骤都可以单独运行,档案的状态检查/编辑整个过程.

`process()` 财务报告和审定财务报表 `finalize()` 在成功或失败时释放输出资源。 工人在编制索引后关闭。 应使用递增呼叫器 `finally` 如果任何步骤失败或归档被放弃,则处理归档:

```javascript
const archive = new WACZ({ input: 'collection/*.warc.gz', output: 'collection.wacz' })
try {
  await archive.addFileToZip(Buffer.from('Extra data'), 'extras/data.txt')
  await archive.process()
} finally {
  await archive.dispose()
}
```

`dispose()` 可以反复调用,并留下一个成功定稿的文件。 已完成或处理的示例无法启动另一出口.

### 支付费用

-   `WACZ.addPage()` 允许手动将条目添加到 `pages.jsonl`。 。 。 .
-   `WACZ.addFileToZip()` 允许手动将任何额外数据添加到最后WACZ文件中.
-   这个 `datapackageExtras` 选项允许在数据包中添加任意的 JSON 序列大小对象 `extras`。 。 。 .

### 参考文献:

-   [WACZ 类](https://github.com/harvard-lil/js-wacz/blob/main/index.js)
-   [可用选项](https://github.com/harvard-lil/js-wacz/blob/main/types.js)

[\* 回到摘要](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-summary)

* * *

## 与 py-wacz 的特征均等

**兹-瓦兹** 旨在部分特征与 [网络录音器的 py -wacz](https://specs.webrecorder.net/wacz/1.1.1/),类似于 [网络录音器的 py -wacz](https://github.com/webrecorder/py-wacz)。 。 。 .

本节列出了可能影响到互操作性的实施方面的显著差异.

**目前实施的特点的主要差异:**

-   **CLI: 爱丽丝** `create --detect-pages`数字 : `--detect-pages` 包含在 **兹-瓦兹** 除非 `--pages` 提供.
-   **CLI: 爱丽丝** `create --file`:这一论点可以指: **皮瓦兹语name**,它总是明确在 **兹-瓦兹**。 。 。 .

[\* 回到摘要](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-summary)

* * *

## 发展

### 标准联合来文

此代码库使用 [标准联合来文](https://standardjs.com/) 编码样式.

-   `npm run lint` 可用于检查格式.
-   `npm run lint-autofix` 可用于检查格式 _财务报告和审定财务报表_ 尽可能自动相应编辑文件.
-   大多数IDE可以被配置到自动检查并强制执行这种编码样式.

### 联合来文文件

[联合来文文件](https://jsdoc.app/) 用于该项目的文件和松散类型检查.

### 测试

这个项目使用 [节点Js的内置测试跑道](https://nodejs.org/api/test.html)。 。 。 .

```bash
npm run test
```

套接字开始并停止其本地 HTTP 签名服务器,生成真实 加密签名,并检查独立的RSA/ECDSA证书固定装置.

### 可用的 CLI

```bash
# Runs test suite
npm run test

# Runs linter
npm run lint

# Runs linter and attempts to automatically fix issues
npm run lint-autofix

# Step-by-step NPM publishing helper
npm run publish-util

```

[\* 回到摘要](https://npmcn.com/package/%40harvard-lil/js-wacz/#readme-summary)

## 常见问题

### @harvard-lil/js-wacz 是什么？

JavaScript模块和CLI工具,用于使用WACZ格式规格处理网络存档数据\.

### 如何安装 @harvard-lil/js-wacz？

在项目目录运行 npm install @harvard-lil/js-wacz，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 js-wacz，可以用 npx js-wacz 直接运行。

### @harvard-lil/js-wacz 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/harvard-lil\_\_js-wacz 是否存在。

### @harvard-lil/js-wacz 支持 ESM 还是 CommonJS？

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

### @harvard-lil/js-wacz 需要什么版本的 Node\.js？

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

### @harvard-lil/js-wacz 可以商用吗？

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

### @harvard-lil/js-wacz 的下载量有多少？

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

### @harvard-lil/js-wacz 还在维护吗？

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

