# @ctrl/torrent-file 中文文档

规范地址：https://npmcn.com/package/%40ctrl/torrent-file/

版本：4\.5\.2
npm 元数据更新时间：2026-10-04T16:03:26.970Z
中文译文更新时间：2026-11-11T03:52:45.148Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ctrl/torrent-file
原文对照：https://npmcn.com/package/%40ctrl/torrent-file/?lang=original
项目主页：https://torrent-file.pages.dev/
源码仓库：https://github.com/scttcper/torrent-file

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

- 包体积（解压后）：42.1 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>20
- 运行依赖：0 个
- 首次发布：2019-05-18T23:01:42.781Z
- 最新版本发布：2026-10-04T16:03:26.612Z
- 近 30 天下载量：8678（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 3 个）

## 中文简介

分析种子文件( 名称、 散列、 文件、 部件)

## 安装

```sh
npm install @ctrl/torrent-file
```

也可以使用：`pnpm add @ctrl/torrent-file`、`yarn add @ctrl/torrent-file`、`bun add @ctrl/torrent-file`

## README

# 种子文件 [![npm](https://badgen.net/npm/v/@ctrl/torrent-file)](https://www.npmjs.com/package/@ctrl/torrent-file)

> 分析、检查和编码 BitTorrent metainfo 文件.

支持 BitTorrent v1 (帮助[最佳环境做法3](https://www.bittorrent.org/beps/bep_0003.html)页:1[BEP 52 最佳环境做法](https://www.bittorrent.org/beps/bep_0052.html)),和包含两种格式的混合种子文件.

该项目的基础是: [解析格式](https://www.npmjs.com/package/parse-torrent) 财务报告和审定财务报表 [节点编码](https://github.com/themasch/node-bencode)它包括严格的 [编码](https://www.bittorrent.org/beps/bep_0003.html#bencoding) 在周围建造了编码器和解码器 `Uint8Array` 而不是节点.js `Buffer`。 。 。 .

发音: [https://torrent-file.pages.dev 互联网档案馆的存檔,存档日期2013-12-21](https://torrent-file.pages.dev/)

## 安装

```console
npm install @ctrl/torrent-file
```

## API 密码

### `info(file)`

返回显示元数据、跟踪器、网络种子和检测到的 `version`数字 : `'v1'`, (中文(简体) ), `'v2'`,或 `'hybrid'`。 。 。 .

```ts
import fs from 'fs';

import { info } from '@ctrl/torrent-file';

const torrentInfo = info(fs.readFileSync('myfile'));
console.log({ torrentInfo });
```

### `files(file)`

返回文件和块信息 :

-   `length` 是列出文件长度的总和.
-   `offset` 是协议块空间中文件的字节偏移。 BEP 52 将每个非空的 v2 文件对齐到一块边界,因此 v2 偏移可以包含不包含在其中的缺口 `length`。 。 。 .
-   `pieces` 包含 v1/ hybrid torrents 的十六进制 SHA-1 散列, 而 v2- 只包含 torrents 则不包含 .
-   `piecesRoot` 是一个十六进制的 SHA-256 Merkle root 在 v2/hybrid 文件中.
-   `pieceLayers` 将十六进制片根映射到十六进制的数组 SHA-256 散列.

路径使用主机平台的路径分隔符. 对于 v2 种子, 咨询种子 `name` 准备到BEP 52文件树返回的路径.

```ts
import fs from 'fs';

import { files } from '@ctrl/torrent-file';

const torrentFiles = files(fs.readFileSync('myfile'));
console.log({ torrentFiles });
```

### `hash(file)`

返回 v1 SHA-1 信息散列 。 它只为 v2 种子扔出, 因为种子没有 v1 身份 .

```ts
import fs from 'fs';

import { hash } from '@ctrl/torrent-file';

const torrentHash = hash(fs.readFileSync('myfile'));
console.log({ torrentHash });
```

### `hashV2(file)`

返回完整的32字节 v2 SHA-256信息散列为十六进制. 它只为 v1- torrent.

```ts
import fs from 'fs';

import { hashV2 } from '@ctrl/torrent-file';

const torrentHashV2 = hashV2(fs.readFileSync('myfile'));
console.log({ torrentHashV2 });
```

### `hashes(file)`

返回可用的 v1( SHA-1) 和 v2( SHA-256) 信息散列以及检测到的 torrent 版本 . `infoHash` 用于 v1 和混合种子; `infoHashV2` 用于 v2 和混合种子.

```ts
import fs from 'fs';

import { hashes } from '@ctrl/torrent-file';

const h = hashes(fs.readFileSync('myfile'));
console.log(h.version); // 'v1', 'v2', or 'hybrid'
console.log(h.infoHash); // SHA-1 (v1/hybrid only)
console.log(h.infoHashV2); // SHA-256 (v2/hybrid only)
```

信息散列由精确的 Ben 编码计算 `info` 文件所找到的字典字节, 按要求 [最佳环境做法3](https://www.bittorrent.org/beps/bep_0003.html#trackers) 财务报告和审定财务报表 [BEP 52 最佳环境做法](https://www.bittorrent.org/beps/bep_0052.html#infohash)。它们不是从解码/编码往返计算.

### 低等贝恩码

`decode()` 返回被编码的字节字符串为 `Uint8Array`,包括用作字典值的字节字符串。 已解码的词典有一个无效的原型,所以键如 `__proto__`, (中文(简体) ), `constructor`,以及 `toString` 是普通的自有属性,而不是被继承的JavaScript行为. `encode()` 接受字符串, `Uint8Array`、安全整数、数组和词典.

解码器拒绝非卡通或不完整的本码,包括无序/重复的字典密钥,领先-零整数,负零,不安全整数,截取值,以及后缀数据. 更高级的解析和散列函数使用相同的严格解码器,并因此投放不正确的输入.

词典键可以是任意字节. 解码词典保留足够的内部信息 `encode(decode(data))` 保存二进制键, 如 BEP 52 块根 。 新构造的文字字典密钥为UTF-8编码.

## 编码

将已解析的种子对象返回到一个 `.torrent` 文件缓冲器.

```ts
import fs from 'fs';

import { toTorrentFile } from '@ctrl/torrent-file';

// Minimal example: create a .torrent buffer from fields
const buf = toTorrentFile({
  info: {
    // Required info fields
    'piece length': 16384,
    pieces: new Uint8Array(/* 20-byte SHA1 hashes concatenated */),
    name: 'example.txt',
    length: 12345,
  },
  // Optional fields
  announce: ['udp://tracker.publicbt.com:80/announce'],
  urlList: ['https://example.com/example.txt'],
  private: false,
  created: new Date(),
  createdBy: 'my-app/1.0.0',
  comment: 'Generated by @ctrl/torrent-file',
});

fs.writeFileSync('example.torrent', buf);
```

`toTorrentFile()` 序列化所提供的元数据;它不读取文件内容,不计算出片段散列,不构建 v2 Merkle 树,也不插入混合编码文件.

用于 v2 `pieceLayers`,字典密钥是原始的32字节片根而不是十六进制文本. 在手动构建时, 以 JavaScript 字符代表每个字节 :

```ts
const rawDictionaryKey = (bytes: Uint8Array) => String.fromCharCode(...bytes);

const buf = toTorrentFile({
  info: v2Info,
  pieceLayers: {
    [rawDictionaryKey(piecesRoot)]: concatenatedLayerHashes,
  },
});
```

这个 `pieceLayers` 返回时间 `files()` 是一个方便显示的十六进制表示式,不是被 `toTorrentFile()`。 。 。 .

## 审定范围

剖析器验证了canonical bencoding及其所消耗的v1/v2文件-信息结构,包括v2元数据版本,块大小,文件树形状,文件长度,片根,和散列字节长度.

它不重算文件散列,不用密码验证块层与默克勒根相比,也不证明混合种子的v1和v2侧描述相同内容. 应用程序下载或信任内容必须分别进行这些完整性检查.

## 演示

运行本地演示 UI 以丢出一个 `.torrent` 文件与视图解析输出 :

```bash
pnpm install
pnpm demo:watch
```

要构建静态托管的演示:

```bash
pnpm demo:build
```

## 规格和相关项目

-   [BEP 3 — BitTorrent 协议 v1 和编码](https://www.bittorrent.org/beps/bep_0003.html)
-   [BEP 12——多跟踪元数据](https://www.bittorrent.org/beps/bep_0012.html)
-   [BEP 19——网络种子](https://www.bittorrent.org/beps/bep_0019.html)
-   [BEP 47 — 编码文件和扩展文件属性](https://www.bittorrent.org/beps/bep_0047.html)
-   [BEP 52 — BitTorrent 协议 v2 和混合种子](https://www.bittorrent.org/beps/bep_0052.html)
-   [解析格式](https://www.npmjs.com/package/parse-torrent)
-   [节点编码](https://github.com/themasch/node-bencode)

## 常见问题

### @ctrl/torrent-file 是什么？

分析种子文件\( 名称、 散列、 文件、 部件\)

### 如何安装 @ctrl/torrent-file？

在项目目录运行 npm install @ctrl/torrent-file，或使用 pnpm add / yarn add / bun add。

### @ctrl/torrent-file 支持 TypeScript 吗？

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

### @ctrl/torrent-file 支持 ESM 还是 CommonJS？

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

### @ctrl/torrent-file 需要什么版本的 Node\.js？

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

### @ctrl/torrent-file 可以商用吗？

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

### @ctrl/torrent-file 的下载量有多少？

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

### @ctrl/torrent-file 还在维护吗？

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