# @ctrl/magnet-link 中文文档

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

版本：5\.0\.1
npm 元数据更新时间：2026-10-04T16:05:07.641Z
中文译文更新时间：2026-11-11T03:51:46.887Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：19.4 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>20
- 运行依赖：2 个
- 首次发布：2019-02-26T20:39:24.117Z
- 最新版本发布：2026-10-04T16:05:07.307Z
- 近 30 天下载量：9713（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 4 个）

## 中文简介

将磁铁 URI 分析成对象

## 安装

```sh
npm install @ctrl/magnet-link
```

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

## README

# 磁铁连接 [![npm](https://badgen.net/npm/v/@ctrl/magnet-link)](https://www.npmjs.com/package/@ctrl/magnet-link) [![coverage](https://badgen.net/codecov/c/github/scttcper/magnet-link)](https://codecov.io/gh/scttcper/magnet-link)

> 将磁铁 URI 分析成对象

港口 [网约车/磁铁里](https://github.com/webtorrent/magnet-uri) 以 [恶作剧](https://github.com/feross) 在打字符中使用较少的依赖性

**演示**数字 : [https://magnet-link.ep.works.dev 互联网档案馆的存檔,存档日期2013-12-02](https://magnet-link.ep.workers.dev/)

### 安装

```console
npm install @ctrl/magnet-link
```

### 使用

#### 解码

```ts
import { magnetDecode } from '@ctrl/magnet-link';

const uri =
  'magnet:?xt=urn:btih:d2474e86c95b19b8bcfdb92bc12c9d44667cfa36&dn=Leaves+of+Grass+by+Walt+Whitman.epub&tr=udp%3A%2F%2Ftracker.example4.com%3A80&tr=udp%3A%2F%2Ftracker.example5.com%3A80&tr=udp%3A%2F%2Ftracker.example3.com%3A6969&tr=udp%3A%2F%2Ftracker.example2.com%3A80&tr=udp%3A%2F%2Ftracker.example1.com%3A1337';
const parsed = magnetDecode(uri);
console.log(parsed.dn); // "Leaves of Grass by Walt Whitman.epub"
console.log(parsed.infoHash); // "d2474e86c95b19b8bcfdb92bc12c9d44667cfa36"
```

整个解析对象

```json
{
  "xt": "urn:btih:d2474e86c95b19b8bcfdb92bc12c9d44667cfa36",
  "dn": "Leaves of Grass by Walt Whitman.epub",
  "tr": [
    "udp://tracker.example4.com:80",
    "udp://tracker.example5.com:80",
    "udp://tracker.example3.com:6969",
    "udp://tracker.example2.com:80",
    "udp://tracker.example1.com:1337"
  ],
  "name": "Leaves of Grass by Walt Whitman.epub",
  "infoHash": "d2474e86c95b19b8bcfdb92bc12c9d44667cfa36",
  "announce": [
    "udp://tracker.example4.com:80",
    "udp://tracker.example5.com:80",
    "udp://tracker.example3.com:6969",
    "udp://tracker.example2.com:80",
    "udp://tracker.example1.com:1337"
  ]
}
```

重复的跟踪器,网络种子,和对等地址按照插入顺序被去除.

#### 编码

```ts
import { magnetEncode } from '@ctrl/magnet-link';

// convert object to magnet uri
const uri = magnetEncode({
  xt: [
    'urn:ed2k:354B15E68FB8F36D7CD88FF94116CDC1',
    'urn:tree:tiger:7N5OAMRNGMSSEUE3ORHOKWN4WWIQ5X4EBOOTLJY',
    'urn:btih:QHQXPYWMACKDWKP47RRVIV7VOURXFE5Q',
  ],
  xl: '10826029',
  dn: 'mediawiki-1.15.1.tar.gz',
  tr: ['udp://tracker.openbittorrent.com:80/announce'],
  as: 'http://download.wikimedia.org/mediawiki/1.15/mediawiki-1.15.1.tar.gz',
  xs: ['http://cache.example.org/XRX2PEFXOOEJFRVUCX6HMZMKS5TWG4K5', 'dchub://example.org'],
});
```

也可以使用名称(dn),infoHash(xt),infoHashIntArray(xt),公告(tr),关键词(kt),公钥(xs)和盐(s)等方便键名.

```ts
const hybrid = magnetEncode({
  infoHash: '631a31dd0a46257d5078c0dee4e66e26f73e42ac',
  infoHashV2: 'd8dd32ac93357c368556af3ac1d95c9d76bd0dff6fa9833ecdac3d53134efabb',
});

const mutable = magnetEncode({
  publicKey: '8543d3e6115f0f98c944077a4493dcd543e49c739fd998550a1f614ab36ed63e',
  salt: '6e',
});

const selectOnly = magnetEncode({
  infoHash: 'd2474e86c95b19b8bcfdb92bc12c9d44667cfa36',
  so: [0, 2, 4, 6, 7, 8],
});
```

### 另见

-   磁铁里 [https://github.com/webtorrent/magnet-uri (英语)](https://github.com/webtorrent/magnet-uri)
-   BEP9 - 同行发送元数据文件的扩展 [http://www.bittorrent.org/beps/bep 0009.html (中文(简体) )](http://www.bittorrent.org/beps/bep_0009.html)
-   BEP46 - 更新种子 Via DHT 可变项目 [http://www.bittorrent.org/beps/bep 0046.html (中文(简体) )](http://www.bittorrent.org/beps/bep_0046.html)
-   BEP53 - Magnet URI 扩展名 - 选择特定文件索引下载 [http://www.bittorrent.org/beps/bep 0053.html (中文(简体) )](http://www.bittorrent.org/beps/bep_0053.html)

## 常见问题

### @ctrl/magnet-link 是什么？

将磁铁 URI 分析成对象

### 如何安装 @ctrl/magnet-link？

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

### @ctrl/magnet-link 支持 TypeScript 吗？

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

### @ctrl/magnet-link 支持 ESM 还是 CommonJS？

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

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

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

### @ctrl/magnet-link 可以商用吗？

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

### @ctrl/magnet-link 的下载量有多少？

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

### @ctrl/magnet-link 还在维护吗？

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