# @gathertown/msgpack 中文文档

规范地址：https://npmcn.com/package/%40gathertown/msgpack/

版本：3\.1\.3
npm 元数据更新时间：2026-05-11T19:02:26.085Z
中文译文更新时间：2026-11-16T00:02:32.979Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：666 kB，112 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18
- 运行依赖：0 个
- 首次发布：2024-11-22T04:34:22.311Z
- 最新版本发布：2026-05-11T19:02:25.917Z
- 近 30 天下载量：12180（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 1 个）

## 中文简介

ECMA-262/JavaScript/ TypeScript 信件包

## 安装

```sh
npm install @gathertown/msgpack
```

也可以使用：`pnpm add @gathertown/msgpack`、`yarn add @gathertown/msgpack`、`bun add @gathertown/msgpack`

## README

# ECMA-262/JavaScript/ TypeScript 信件包

[![npm version](https://img.shields.io/npm/v/@msgpack/msgpack.svg)](https://www.npmjs.com/package/@msgpack/msgpack) ![CI](https://github.com/msgpack/msgpack-javascript/workflows/CI/badge.svg) [![codecov](https://codecov.io/gh/msgpack/msgpack-javascript/branch/master/graphs/badge.svg)](https://codecov.io/gh/msgpack/msgpack-javascript) [![minzip](https://badgen.net/bundlephobia/minzip/@msgpack/msgpack)](https://bundlephobia.com/result?p=@msgpack/msgpack) [![tree-shaking](https://badgen.net/bundlephobia/tree-shaking/@msgpack/msgpack)](https://bundlephobia.com/result?p=@msgpack/msgpack)

这个图书馆是执行 **邮件包** 用于TypeScript和JavaScript,提供紧凑而高效的二进制序列化格式. 了解更多关于 MessagePack 的信息 :

[https://msgpack.org/ (中文(简体) )](https://msgpack.org/)

这个库是JavaScript的MessagePack的全面参考执行,其重点是准确性,兼容性,互操作性,以及性能.

此外,这也是通用的JavaScript库. 它不仅与浏览器兼容,而且与Node.js或其他执行ES2015+标准的JavaScript引擎兼容. 如书所记 [类型脚本](https://www.typescriptlang.org/),这个库会捆绑最新的类型定义文件(`d.ts`) (中文(简体) ).

\*注意这是"MessagePack for JavaScript"的第二版. 第一版在ES5中实施,从未被发布到npmjs.com,被标记为: [`classic`](https://github.com/msgpack/msgpack-javascript/tree/classic)。 。 。 .

## 概要

```typescript
import { deepStrictEqual } from "assert";
import { encode, decode } from "@msgpack/msgpack";

const object = {
  nil: null,
  integer: 1,
  float: Math.PI,
  string: "Hello, world!",
  binary: Uint8Array.from([1, 2, 3]),
  array: [10, 20, 30],
  map: { foo: "bar" },
  timestampExt: new Date(),
};

const encoded: Uint8Array = encode(object);

deepStrictEqual(decode(encoded), object);
```

## 目录

-   [概要](https://npmcn.com/package/%40gathertown/msgpack/#readme-synopsis)
-   [目录](https://npmcn.com/package/%40gathertown/msgpack/#readme-table-of-contents)
-   [安装](https://npmcn.com/package/%40gathertown/msgpack/#readme-install)
-   [API 密码](https://npmcn.com/package/%40gathertown/msgpack/#readme-api)
    -   [`encode(data: unknown, options?: EncoderOptions): Uint8Array`](https://npmcn.com/package/%40gathertown/msgpack/#readme-encodedata-unknown-options-encoderoptions-uint8array)
        -   [`EncoderOptions`](https://npmcn.com/package/%40gathertown/msgpack/#readme-encoderoptions)
    -   [`decode(buffer: ArrayLike<number> | BufferSource, options?: DecoderOptions): unknown`](https://npmcn.com/package/%40gathertown/msgpack/#readme-decodebuffer-arraylikenumber--buffersource-options-decoderoptions-unknown)
        -   [`DecoderOptions`](https://npmcn.com/package/%40gathertown/msgpack/#readme-decoderoptions)
    -   [`decodeMulti(buffer: ArrayLike<number> | BufferSource, options?: DecoderOptions): Generator<unknown, void, unknown>`](https://npmcn.com/package/%40gathertown/msgpack/#readme-decodemultibuffer-arraylikenumber--buffersource-options-decoderoptions-generatorunknown-void-unknown)
    -   [`decodeAsync(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecoderOptions): Promise<unknown>`](https://npmcn.com/package/%40gathertown/msgpack/#readme-decodeasyncstream-readablestreamlikearraylikenumber--buffersource-options-decoderoptions-promiseunknown)
    -   [`decodeArrayStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecoderOptions): AsyncIterable<unknown>`](https://npmcn.com/package/%40gathertown/msgpack/#readme-decodearraystreamstream-readablestreamlikearraylikenumber--buffersource-options-decoderoptions-asynciterableunknown)
    -   [`decodeMultiStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecoderOptions): AsyncIterable<unknown>`](https://npmcn.com/package/%40gathertown/msgpack/#readme-decodemultistreamstream-readablestreamlikearraylikenumber--buffersource-options-decoderoptions-asynciterableunknown)
    -   [重用编码器和解码器实例](https://npmcn.com/package/%40gathertown/msgpack/#readme-reusing-encoder-and-decoder-instances)
-   [扩展类型](https://npmcn.com/package/%40gathertown/msgpack/#readme-extension-types)
    -   [扩展Codec 上下文](https://npmcn.com/package/%40gathertown/msgpack/#readme-extensioncodec-context)
    -   [处理扩展大小](https://npmcn.com/package/%40gathertown/msgpack/#readme-handling-bigint-with-extensioncodec)
    -   [时间模块作为时间戳扩展](https://npmcn.com/package/%40gathertown/msgpack/#readme-the-temporal-module-as-timestamp-extensions)
-   [更快地解码一大批浮点数](https://npmcn.com/package/%40gathertown/msgpack/#readme-faster-way-to-decode-a-large-array-of-floating-point-numbers)
-   [正在解码 Blob](https://npmcn.com/package/%40gathertown/msgpack/#readme-decoding-a-blob)
-   [信件包规格](https://npmcn.com/package/%40gathertown/msgpack/#readme-messagepack-specification)
    -   [信件包映射表](https://npmcn.com/package/%40gathertown/msgpack/#readme-messagepack-mapping-table)
-   [先决条件](https://npmcn.com/package/%40gathertown/msgpack/#readme-prerequisites)
    -   [ECMA-262号](https://npmcn.com/package/%40gathertown/msgpack/#readme-ecma-262)
    -   [节点JS](https://npmcn.com/package/%40gathertown/msgpack/#readme-nodejs)
    -   [类型脚本编译器/ 类型定义](https://npmcn.com/package/%40gathertown/msgpack/#readme-typescript-compiler--type-definitions)
-   [基准](https://npmcn.com/package/%40gathertown/msgpack/#readme-benchmark)
-   [分发](https://npmcn.com/package/%40gathertown/msgpack/#readme-distribution)
    -   [国家预防机制/npmjs.com](https://npmcn.com/package/%40gathertown/msgpack/#readme-npm--npmjscom)
    -   [CDN / unpkg.com (中文(简体) )](https://npmcn.com/package/%40gathertown/msgpack/#readme-cdn--unpkgcom)
-   [德诺支持](https://npmcn.com/package/%40gathertown/msgpack/#readme-deno-support)
-   [Bun 支持](https://npmcn.com/package/%40gathertown/msgpack/#readme-bun-support)
-   [维修](https://npmcn.com/package/%40gathertown/msgpack/#readme-maintenance)
    -   [测试](https://npmcn.com/package/%40gathertown/msgpack/#readme-testing)
    -   [持续整合](https://npmcn.com/package/%40gathertown/msgpack/#readme-continuous-integration)
    -   [单元工程](https://npmcn.com/package/%40gathertown/msgpack/#readme-release-engineering)
    -   [更新依赖关系](https://npmcn.com/package/%40gathertown/msgpack/#readme-updating-dependencies)
-   [许可证](https://npmcn.com/package/%40gathertown/msgpack/#readme-license)

## 安装

此库发布到 `npmjs.com` 作为 [@ msgpack/ msgpack (英语)](https://www.npmjs.com/package/@msgpack/msgpack)。 。 。 .

```shell
npm install @msgpack/msgpack
```

## API 密码

### `encode(data: unknown, options?: EncoderOptions): Uint8Array`

密码 `data` 返回一个字节数组为 `Uint8Array`如果 `data` 属于或包括一个非连续物体,例如 `function` 或一个 `symbol`。 。 。 .

例如:

```typescript
import { encode } from "@msgpack/msgpack";

const encoded: Uint8Array = encode({ foo: "bar" });
console.log(encoded);
```

如果你想转换一个 `uint8array` 到节点JS `Buffer`,使用时 `Buffer.from(arrayBuffer, offset, length)` 为了不复制基础 `ArrayBuffer`时 `Buffer.from(uint8array)` 复制它:

```typescript
import { encode } from "@msgpack/msgpack";

const encoded: Uint8Array = encode({ foo: "bar" });

// `buffer` refers the same ArrayBuffer as `encoded`.
const buffer: Buffer = Buffer.from(encoded.buffer, encoded.byteOffset, encoded.byteLength);
console.log(buffer);
```

#### `EncoderOptions`

| 名称 | 类型 | 默认 |
| --- | --: | --: |
| 扩展代码 | 扩展编码 | `ExtensionCodec.defaultCodec` |
| 上下文 | 用户定义 | \- 说吧 |
| 使用BigInt64系统 | 布尔 | 虚假 |
| 最大深度 | 编号 | `100` |
| 初始缓冲大小 | 编号 | `2048` |
| 排序键 | 布尔 | 虚假 |
| 部队32 | 布尔 | 虚假 |
| 强制整流器 | 布尔 | 虚假 |
| 忽略未定义 | 布尔 | 虚假 |

### `decode(buffer: ArrayLike<number> | BufferSource, options?: DecoderOptions): unknown`

它解码 `buffer` 中包含一个已编码信件对象,并返回已解码对象 `unknown`。 。 。 .

`buffer` 必须是字节数组, 通常是 `Uint8Array` 或者说 `ArrayBuffer`。 。 。 . `BufferSource` 定义为 `ArrayBuffer | ArrayBufferView`。 。 。 .

这个 `buffer` 必须包含单个编码对象。 如果 `buffer` 包括对象或对象之后的额外字节 `buffer` 这是空的,它扔 `RangeError`解码 `buffer` 包含多个编码对象,使用 `decodeMulti()` 或者说 `decodeMultiStream()` (推荐)取而代之.

例如:

```typescript
import { decode } from "@msgpack/msgpack";

const encoded: Uint8Array;
const object = decode(encoded);
console.log(object);
```

节点JS `Buffer` 也可以接受,因为它是 `Uint8Array`。 。 。 .

#### `DecoderOptions`

| 名称 | 类型 | 默认 |
| --- | --: | --: |
| 扩展代码 | 扩展编码 | `ExtensionCodec.defaultCodec` |
| 上下文 | 用户定义 | \- 说吧 |
| 使用BigInt64系统 | 布尔 | 虚假 |
| 原始结构 | 布尔 | 虚假 |
| 最大边距 | 编号 | `4_294_967_295` (UINT32 MAX) (英语) |
| 最大边框 | 编号 | `4_294_967_295` (UINT32 MAX) (英语) |
| 最大箭头 | 编号 | `4_294_967_295` (UINT32 MAX) (英语) |
| 最大映射线 | 编号 | `4_294_967_295` (UINT32 MAX) (英语) |
| 最大扩展线 | 编号 | `4_294_967_295` (UINT32 MAX) (英语) |
| 映射键计算器 | 映射 Key Converter 类型 | 如果密钥不是字符串或数字, 则丢弃例外 |

`MapKeyConverterType` 定义为 `(key: unknown) => string | number`。 。 。 .

为了跳过UTF-8的字符串解码, `rawStrings` 可设定为 `true`。在这种情况下,字符串被解码为 `Uint8Array`。 。 。 .

你用得着 `max${Type}Length` 以限制每个类型已解码的长度.

### `decodeMulti(buffer: ArrayLike<number> | BufferSource, options?: DecoderOptions): Generator<unknown, void, unknown>`

它解码 `buffer` ,包括多个MessagePack编码对象,并返回解码对象作为生成器。 另见 `decodeMultiStream()`,这是此函数的一个同步变体.

此功能不推荐通过 I/O 流解码 MessagePack 二进制, 包括套接字, 因为它是同步的 。 相反, `decodeMultiStream()` 同步地解码一二进制流,通常花费更少的CPU和内存.

例如:

```typescript
import { decode } from "@msgpack/msgpack";

const encoded: Uint8Array;

for (const object of decodeMulti(encoded)) {
  console.log(object);
}
```

### `decodeAsync(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecoderOptions): Promise<unknown>`

它解码 `stream`时 `ReadableStreamLike<T>` 定义为 `ReadableStream<T> | AsyncIterable<T>`,在字节数组中,返回已解码的对象为 `unknown` 类型,以 `Promise`。 。 。 .

此函数同步工作, 并且可能比同步更高效地使用 CPU 资源 `decode()`,因为它不等待完成下载.

此功能旨在与 whg 工作 `fetch()` 像这样:

```typescript
import { decodeAsync } from "@msgpack/msgpack";

const MSGPACK_TYPE = "application/x-msgpack";

const response = await fetch(url);
const contentType = response.headers.get("Content-Type");
if (contentType && contentType.startsWith(MSGPACK_TYPE) && response.body != null) {
  const object = await decodeAsync(response.body);
  // do something with object
} else { /* handle errors */ }
```

### `decodeArrayStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecoderOptions): AsyncIterable<unknown>`

一样 `decodeAsync()`,但仅接受 `stream` 中包含一系列项目,并逐一发出已解码的项目.

例如:

```typescript
import { decodeArrayStream } from "@msgpack/msgpack";

const stream: AsyncIterator<Uint8Array>;

// in an async function:
for await (const item of decodeArrayStream(stream)) {
  console.log(item);
}
```

### `decodeMultiStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecoderOptions): AsyncIterable<unknown>`

一样 `decodeAsync()` 财务报告和审定财务报表 `decodeArrayStream()`输入 `stream` 必须包含多个信息包编码项目。 这是一个同步变体,用于 `decodeMulti()`。 。 。 .

换句话说,它可以解码无限流并逐一出出解码项目.

例如:

```typescript
import { decodeMultiStream } from "@msgpack/msgpack";

const stream: AsyncIterator<Uint8Array>;

// in an async function:
for await (const item of decodeMultiStream(stream)) {
  console.log(item);
}
```

此函数自 v 2. 4. 0 起可用;以前称为 `decodeStream()`。 。 。 .

### 重用编码器和解码器实例

`Encoder` 财务报告和审定财务报表 `Decoder` 通过重用实例提供类,以取得更好的性能:

```typescript
import { deepStrictEqual } from "assert";
import { Encoder, Decoder } from "@msgpack/msgpack";

const encoder = new Encoder();
const decoder = new Decoder();

const encoded: Uint8Array = encoder.encode(object);
deepStrictEqual(decoder.decode(encoded), object);
```

根据我们的基准 重用 `Encoder` 例速约20% 比起来 `encode()` 函数和重用 `Decoder` 实例速度约2% 比起来 `decode()` 函数。 注意其结果应因环境而异 和数据结构.

`Encoder` 财务报告和审定财务报表 `Decoder` 使用与 `encode()` 财务报告和审定财务报表 `decode()` 页:1.

## 扩展类型

处理 [信件包扩展类型](https://github.com/msgpack/msgpack/blob/master/spec.md#extension-types),该图书馆提供 `ExtensionCodec` 课.

这是设置自定义扩展类型处理的示例 `Map` 财务报告和审定财务报表 `Set` 类型脚本中的类 :

```typescript
import { encode, decode, ExtensionCodec } from "@msgpack/msgpack";

const extensionCodec = new ExtensionCodec();

// Set<T>
const SET_EXT_TYPE = 0 // Any in 0-127
extensionCodec.register({
  type: SET_EXT_TYPE,
  encode: (object: unknown): Uint8Array | null => {
    if (object instanceof Set) {
      return encode([...object], { extensionCodec });
    } else {
      return null;
    }
  },
  decode: (data: Uint8Array) => {
    const array = decode(data, { extensionCodec }) as Array<unknown>;
    return new Set(array);
  },
});

// Map<K, V>
const MAP_EXT_TYPE = 1; // Any in 0-127
extensionCodec.register({
  type: MAP_EXT_TYPE,
  encode: (object: unknown): Uint8Array => {
    if (object instanceof Map) {
      return encode([...object], { extensionCodec });
    } else {
      return null;
    }
  },
  decode: (data: Uint8Array) => {
    const array = decode(data, { extensionCodec }) as Array<[unknown, unknown]>;
    return new Map(array);
  },
});

const encoded = encode([new Set<any>(), new Map<any, any>()], { extensionCodec });
const decoded = decode(encoded, { extensionCodec });
```

确保您在任何递归编码和解码语句中包含扩展Codec!

注意自定义对象的扩展类型必须是 `[0, 127]`时 `[-1, -128]` 保留给 MessagePack 本身.

### 扩展Codec 上下文

当您使用扩展编码器时,可能需要有编码/解码状态来跟踪哪些对象被编码/再创建. 要做到这一点,通过一个 `context` 页:1 `EncoderOptions` 财务报告和审定财务报表 `DecoderOptions`数字 :

```typescript
import { encode, decode, ExtensionCodec } from "@msgpack/msgpack";

class MyContext {
  track(object: any) { /*...*/ }
}

class MyType { /* ... */ }

const extensionCodec = new ExtensionCodec<MyContext>();

// MyType
const MYTYPE_EXT_TYPE = 0 // Any in 0-127
extensionCodec.register({
  type: MYTYPE_EXT_TYPE,
  encode: (object, context) => {
    if (object instanceof MyType) {
      context.track(object);
      return encode(object.toJSON(), { extensionCodec, context });
    } else {
      return null;
    }
  },
  decode: (data, extType, context) => {
    const decoded = decode(data, { extensionCodec, context });
    const my = new MyType(decoded);
    context.track(my);
    return my;
  },
});

// and later
import { encode, decode } from "@msgpack/msgpack";

const context = new MyContext();

const encoded = encode({ myType: new MyType<any>() }, { extensionCodec, context });
const decoded = decode(encoded, { extensionCodec, context });
```

### 处理扩展大小

此库不默认处理 BigInt, 但您有两种处理选项 :

-   设定 `useBigInt64: true` 以映射大写到 MessagePack 的 int64/uint64
-   定义自定义 `ExtensionCodec` 将大写映射到信件包的扩展类型

`useBigInt64: true` 这是处理大意最简单的方式,但也有局限性:

-   一个大字节被编码为8字节二进制,即使它是一个小整数
-   大意号必须小于"int64"的最大值并大于"int64"的分分值. 否则,行为是不明确的.

因此,您可能想要定义一个自定义的解码器来处理这样的比特:

```typescript
import { deepStrictEqual } from "assert";
import { encode, decode, ExtensionCodec, DecodeError } from "@msgpack/msgpack";

// to define a custom codec:
const BIGINT_EXT_TYPE = 0; // Any in 0-127
const extensionCodec = new ExtensionCodec();
extensionCodec.register({
  type: BIGINT_EXT_TYPE,
  encode(input: unknown): Uint8Array | null {
    if (typeof input === "bigint") {
      if (input <= Number.MAX_SAFE_INTEGER && input >= Number.MIN_SAFE_INTEGER) {
        return encode(Number(input));
      } else {
        return encode(String(input));
      }
    } else {
      return null;
    }
  },
  decode(data: Uint8Array): bigint {
    const val = decode(data);
    if (!(typeof val === "string" || typeof val === "number")) {
      throw new DecodeError(`unexpected BigInt source: ${val} (${typeof val})`);
    }
    return BigInt(val);
  },
});

// to use it:
const value = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1);
const encoded = encode(value, { extensionCodec });
deepStrictEqual(decode(encoded, { extensionCodec }), value);
```

### 时间模块作为时间戳扩展

有人提议在JavaScript中提出新的日期/时间说明:

-   [https://github.com/tc39/proposition-timporal 互联网档案馆的存檔,存档日期2011-12-22](https://github.com/tc39/proposal-temporal)

这个图书馆地图 `Date` 切换到 MessagePack 时间戳扩展,但您可以重新绘制时间模块(或 [时间多填充](https://github.com/tc39/proposal-temporal/tree/main/polyfill)像这样的时间戳扩展:

```typescript
import { Instant } from "@std-proposal/temporal";
import { deepStrictEqual } from "assert";
import {
  encode,
  decode,
  ExtensionCodec,
  EXT_TIMESTAMP,
  encodeTimeSpecToTimestamp,
  decodeTimestampToTimeSpec,
} from "@msgpack/msgpack";

// to define a custom codec
const extensionCodec = new ExtensionCodec();
extensionCodec.register({
  type: EXT_TIMESTAMP, // override the default behavior!
  encode(input: unknown): Uint8Array | null {
    if (input instanceof Instant) {
      const sec = input.seconds;
      const nsec = Number(input.nanoseconds - BigInt(sec) * BigInt(1e9));
      return encodeTimeSpecToTimestamp({ sec, nsec });
    } else {
      return null;
    }
  },
  decode(data: Uint8Array): Instant {
    const timeSpec = decodeTimestampToTimeSpec(data);
    const sec = BigInt(timeSpec.sec);
    const nsec = BigInt(timeSpec.nsec);
    return Instant.fromEpochNanoseconds(sec * BigInt(1e9) + nsec);
  },
});

// to use it
const instant = Instant.fromEpochMilliseconds(Date.now());
const encoded = encode(instant, { extensionCodec });
const decoded = decode(encoded, { extensionCodec });
deepStrictEqual(decoded, instant);
```

如果时间模块实现标准化,这将成为本库中带有主要版本递增的默认.

## 更快地解码一大批浮点数

如果在你的载荷中有大量浮点数阵列 是更快解码的方法: 定义自定义扩展类型 `Float#Array` 与对齐.

扩展类型 `encode` 方法可以返回一个需要参数的函数 `pos: number`。这个参数可用于调整缓冲, 因此,它解码 更多的表演者.

见实例 `Float32Array`数字 :

```typescript
const extensionCodec = new ExtensionCodec();

const EXT_TYPE_FLOAT32ARRAY = 0; // Any in 0-127
extensionCodec.register({
  type: EXT_TYPE_FLOAT32ARRAY,
  encode: (object: unknown) => {
    if (object instanceof Float32Array) {
      return (pos: number) => {
        const bpe = Float32Array.BYTES_PER_ELEMENT;
        const padding = 1 + ((bpe - ((pos + 1) % bpe)) % bpe);
        const data = new Uint8Array(object.buffer);
        const result = new Uint8Array(padding + data.length);
        result[0] = padding;
        result.set(data, padding);
        return result;
      };
    }
    return null;
  },
  decode: (data: Uint8Array) => {
    const padding = data[0]!;
    const bpe = Float32Array.BYTES_PER_ELEMENT;
    const offset = data.byteOffset + padding;
    const length = data.byteLength - padding;
    return new Float32Array(data.buffer, offset, length / bpe);
  },
});
```

## 正在解码 Blob

[`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) 是浏览器提供的二进制数据容器。 要读取其包含邮件包二进制的内容, 您可以使用 `Blob#arrayBuffer()` 或者说 `Blob#stream()`。 。 。 . `Blob#stream()` 如果目标平台支持,则推荐。 这是因为流出 对大型物体来说,解码速度应该更快。 两种方式,你都需要使用 一个同步 API.

```typescript
async function decodeFromBlob(blob: Blob): unknown {
  if (blob.stream) {
    // Blob#stream(): ReadableStream<Uint8Array> (recommended)
    return await decodeAsync(blob.stream());
  } else {
    // Blob#arrayBuffer(): Promise<ArrayBuffer> (if stream() is not available)
    return decode(await blob.arrayBuffer());
  }
}
```

## 信件包规格

本库与MessagePack规格的"2017年8月"修订版相兼容,此时已添加了时间戳分机:

-   [x] str/bin 离职,2013年8月增加
-   [x] 扩展类型,2013年8月增加
-   [x] 时间戳分机类型,2017年8月添加

生活规格如下:

[https://github.com/msgpack/msgpack 页面存档备份,存于互联网档案馆](https://github.com/msgpack/msgpack)

请注意,截至2019年6月,MessagePack规格上没有正式"版本". 见 [https://github.com/msgpack/msgpack/issues/195 互联网档案馆的存檔,存档日期2011-12-02](https://github.com/msgpack/msgpack/issues/195) 讨论.

### 信件包映射表

下表显示 JavaScript 值的映射方式 [信件包格式](https://github.com/msgpack/msgpack/blob/master/spec.md) 而反之亦然.

整数的映射因设置 `useBigInt64`。 。 。 .

默认, `useBigInt64: false` 为:

| 源值 | 信件包格式 | 数值已解码 |
| --- | --: | --: |
| 无效, 未定义 | 无 | 无效(\*1) |
| 布尔( 真, 假) | 布尔家族 | 布尔( 真, 假) |
| 数字( 53- 位英寸) | 输入家庭 | 编号 |
| 数字( 64- 位浮点) | 浮动家族 | 编号 |
| 字符串 | 家庭关系 | 字符串 (\*2) |
| 线条缓冲维尤 | 宾家 | Uint8 箭头 (\*3) |
| 阵列 | 数组家族 | 阵列 |
| 对象 | 地图家族 | 对象(\*4) |
| 日期 | 时间戳分机家族 | 日期(\*5) |
| 二进制 | 不详 | 不详(\*6) |

-   \*1 两者兼有 `null` 财务报告和审定财务报表 `undefined` 被映射到 `nil` (单位:千美元)`0xC0`)类型,并被解码为 `null`
-   \*2 如果您想要跳过 UTF-8 字符串解码, 设置 `rawStrings: true`。在这种情况下,字符串被解码为 `Uint8Array`。 。 。 .
-   \*3 无 `ArrayBufferView`包括节点JS `Buffer` 被映射到 `bin` 并解码为 `Uint8Array`
-   \*4 处理 `Object`,它被视为 `Record<string, unknown>` 在类型脚本方面
-   \*5 MessagePack时间戳可能有纳秒,解码为JavaScript后会丢失 `Date`。可以通过注册来推翻这种行为 `-1` 用于扩展编码器.
-   \*6 bigint 不支持在 `useBigInt64: false` 模式,但可以定义扩展代码.

如果你准备好了 `useBigInt64: true`,使用下列绘图:

| 源值 | 信件包格式 | 数值已解码 |
| --- | --: | --: |
| 无效, 未定义 | 无 | 无效 |
| 布尔( 真, 假) | 布尔家族 | 布尔( 真, 假) |
| **数字( 32- 位英寸)** | 输入家庭 | 编号 |
| **编号(上述除外)** | 浮动家族 | 编号 |
| **二进制** | int64 / uint64 (英语) | bigint (\*7) (韩语) |
| 字符串 | 家庭关系 | 字符串 |
| 线条缓冲维尤 | 宾家 | Uint8 阵列 |
| 阵列 | 数组家族 | 阵列 |
| 对象 | 地图家族 | 对象 |
| 日期 | 时间戳分机家族 | 日期 |

-   \*7 如果大意大于"int64"的最大值或小于"int64"的分分值,那么行为是未定义的.

## 先决条件

这是一个通用的JavaScript库,支持主要浏览器和节点JS.

### ECMA-262号

-   ES2015语言特征
-   ES2024标准库,包括:
    -   已键入数组( ES2015)
    -   合成(ES2018)
    -   ES2015-ES2022中添加的地物
-   何wg 编码`TextEncoder` 财务报告和审定财务报表 `TextDecoder`(中文(简体) )

ES2022 本库使用的标准库可用多相填充 [核心 js 数据](https://github.com/zloirock/core-js)。 。 。 .

IE11不再被支持. 请使用IE11中的此库,使用v2.x版本.

### 节点JS

需要节点JS v18.

### 类型脚本编译器/ 类型定义

本单元需要类型定义 `AsyncIterator`, (中文(简体) ), `ArrayBufferLike`,Whatwg溪流,等等。 由下列机构提供: `"lib": ["ES2024", "DOM"]` 内 `tsconfig.json`。 。 。 .

关于TypeScript编译器版本,只在开发中测试最新的TypeScript.

## 基准

运行时间性能并不是使用MessagePack的唯一原因,重要的是选择MessagePack库,因此提供了一套基准套件来监控这个库的性能.

V8的内置JSON多年得到改进,esp. `JSON.parse()` 实值 [v8/7.6号文件显著改进](https://v8.dev/blog/v8-release-76)如基准结果bellow所示,它是截至2019年最快的去序列器.

然而,MessagePack可以有效处理二进制数据,实际性能取决于情况. Esp. 如果有效,流出-解码比非流出解码要快得多. 如果表现很重要,你最好用自己的用法做基准.

节点JS/v22.13.1的基准(V8/12.4)

| 操作 | 执行 | 分钟 | 行动 |
| --- | --: | --: | --: |
| buf = 从(JSON.stringify(obj)); | 1348700 (英语) | 5000块 | 269740 (英语) |
| obj = JSON.parse(buf.toString ("utf-8")); | 1700300 (英语) | 5000块 | 340060 (英语) |
| buf = 需要 ("msgpack-lite"). encode(obj;); | 591300 (英语) | 5000块 | 118260 (中文(简体) ) |
| obj = 要求 ("msgpack-lite").decode (buf;); | 539500 (英语) | 5000块 | 107900 (英语) |
| buf = 要求 ("@msgpack/msgpack"). encode (obj) ; | 1238700 (英语) | 5000块 | 247740 (英语) |
| obj = 要求 ("@msgpack/msgpack"). decode (buf) ; | 1402000号 | 5000块 | 280400 (英语) |
| buf=/ \*@msgpack/msgpack \*/编码器.encode(obj); | 1379800 (韩语) | 5000块 | 275960 (英语) |
| obj = / \*@msgpack/msgpack \*/解码器.decode(buf); | 1406100 (英语) | 5000块 | 281220 (英语) |

请注意: `JSON` 案件使用情况 `Buffer` 用于模拟 JavaScript 字符串必须被转换成UTF-8编码的字节数组的 I/O, 而MessagePack 模块处理字节数组.

## 分发

### 国家预防机制/npmjs.com

以npmjs.com分发的国家预防机制包包括ES2015+和ES5文件:

-   `dist/` 与CommomJS一起编译为ES2020,为NodeJS v10提供
-   `dist.umd/` 与 UMD 编译成 ES5
    -   `dist.umd/msgpack.min.js` - 已修改的文件
    -   `dist.umd/msgpack.js` - 未缩小的文件
-   `dist.esm/` 汇编成ES2020,并配有ES模块,为类似网络包装的捆绑器和NodeJS的无害环境管理模式提供

如果使用NodeJS和/或webpack,他们的模块解析器会自动使用合适的.

### CDN / unpkg.com (中文(简体) )

此库可通过 CDN 访问 :

```html
<script crossorigin src="https://unpkg.com/@msgpack/msgpack"></script>
```

装入 `MessagePack` 模块.

## 德诺支持

你可以在德诺使用这个模块.

见 `example/deno-*.ts` 用于实例.

`deno.land/x` 不被支持.

## Bun 支持

您可以在 Bun 上使用此模块 .

## 维修

### 测试

简单的测试:

```
npm run test
```

### 持续整合

此库使用 GitHub 动作 .

测试矩阵 :

-   节点JS
    -   v18/v20/v22 (英语)
-   浏览器 :
    -   火狐克罗姆
-   德诺
-   阿宝

### 单元工程

```console
# run tests on NodeJS, Chrome, and Firefox
make test-all

# edit the changelog
code CHANGELOG.md

# bump version
npm version patch|minor|major

# run the publishing task
make publish
```

### 更新依赖关系

```console
npm run update-dependencies
```

## 许可证

版权2019 腾讯网.

本软件使用ISC许可证:

[https://opensource.org/licenses/ISC 页面存档备份,存于互联网档案馆](https://opensource.org/licenses/ISC)

见 [自由主义](https://npmcn.com/package/%40gathertown/msgpack/LICENSE) 详细情况.

## 常见问题

### @gathertown/msgpack 是什么？

ECMA-262/JavaScript/ TypeScript 信件包

### 如何安装 @gathertown/msgpack？

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

### @gathertown/msgpack 支持 TypeScript 吗？

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

### @gathertown/msgpack 支持 ESM 还是 CommonJS？

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

### @gathertown/msgpack 需要什么版本的 Node\.js？

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

### @gathertown/msgpack 可以商用吗？

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

### @gathertown/msgpack 的下载量有多少？

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

### @gathertown/msgpack 还在维护吗？

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

