# @cratestack/cbor-node 中文文档

规范地址：https://npmcn.com/package/%40cratestack/cbor-node/

版本：0\.17\.2
npm 元数据更新时间：2026-10-31T19:55:45.440Z
中文译文更新时间：2026-10-31T22:22:41.021Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：5.1 MB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-08-03T08:11:05.554Z
- 最新版本发布：2026-10-31T19:55:45.083Z
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

本机N-API cor编解码器，用于CrateStack生成的TypeScript客户端，封装框架自己的cratstack -codec- cor Rust crate (crate / cratstack - cor -napi)，用于与服务器和Rust客户端进行字节相同的连接行为。

## 安装

```sh
npm install @cratestack/cbor-node
```

也可以使用：`pnpm add @cratestack/cbor-node`、`yarn add @cratestack/cbor-node`、`bun add @cratestack/cbor-node`

## README

# @cratestack / cbor-node

原生N-API cor编解码器，用于CrateStack生成的TypeScript RPC客户端 [`CratestackRpcCodec`](https://github.com/cratestack/cratestack/blob/main/packages/cratestack-ts-types/src/index.ts) 由框架自己的支持 [`cratestack-codec-cbor`](https://github.com/cratestack/cratestack/tree/main/crates/cratestack-codec-cbor) 通过本地绑定的Rust crate ([`crates/cratestack-cbor-napi`](https://github.com/cratestack/cratestack/tree/main/crates/cratestack-cbor-napi))， 而不是JS的重新实现。编码/解码输出是字节相同的 CrateStack服务器和Rust客户端已经为 `application/cbor`.

通过。发送预构建的平台二进制文件 `optionalDependencies` (同样的模式 `esbuild`/`@swc/core` use) -不需要Rust工具链来安装或使用这个包。

看到 [史诗# 285](https://github.com/cratestack/cratestack/issues/285) 和 [问题# 286](https://github.com/cratestack/cratestack/issues/286) 以获取完整的设计上下文。

## 使用

```ts
import { cborCodec } from "@cratestack/cbor-node";

const bytes = cborCodec.encode({ hello: "world", count: 1 });
const value = cborCodec.decode(bytes);
```

`cborCodec` 在结构上满足 `CratestackRpcCodec` 从 `@cratestack/ts-types`，所以。 可以传递到任何地方生成的客户端运行时期望一个编解码器-没有显式 依赖 `@cratestack/ts-types` 运行时必需的，因为它是通过 `satisfies`，而不是类型再出口。

## 空处理

cor有一个真实的 `null` (RFC 8949§3.3，简单值22，字节 `0xf6`）。 `cratestack-codec-cbor`的 底层 `minicbor-serde` 后端有一个记录在案的怪癖，其中一个裸露的Rust单元类型 `()` 编码为cor _空数组_ 标记(`0x80`)，而不是这个包裹 `encode` 翻译 每一个JSON `null` （顶级或嵌套在对象/数组中）通过代码路径 产生真正的cor null，匹配 `CborCodec`的自己的 `Option::None` byte-for-byte行为。看到 `crates/cratestack-cbor-napi/src/json_value.rs` 有关细节。

## 错误处理

传入的畸形cor字节 `decode` 抛出一个可捕捉的JS `Error` -从来没有本地崩溃。 两个本地入口点也都使用了api-rs `catch_unwind` 转换任何意外的Rust恐慌 转换为可捕获的异常，而不是中止Node进程。

## 范围

只有单项目编码/解码-没有cor -seq/流支持(这是一个单独的问题；请参阅 史诗般的# 285)。从第746期开始， `@cratestack/cbor` (这个包的Node一半，通过伞 `@cratestack/cbor` 再出口) **是** 生成的TypeScript RPC客户端的默认编解码器- `--no-native-cbor` （`TypeScriptGeneratorConfig::native_cbor: false`)落回 pure-TypeScript `jsonRpcCodec`在此包没有附带napi二进制文件的平台上需要 （`win32-arm64` ——看 `napi.targets` 在 `package.json`）. REST-transport 生成的客户端不会受到任何影响：REST运行时根本没有编解码器接缝。

## 支持的平台上

`napi.targets` 在 `package.json` 是真理的源泉；从cratestack#850开始，它是：

| 平台 | 目标三 | NPM平台包 |
| --- | --- | --- |
| macOS x64 | `x86_64-apple-darwin` | `@cratestack/cbor-node-darwin-x64` |
| macOS arm64 | `aarch64-apple-darwin` | `@cratestack/cbor-node-darwin-arm64` |
| Linux x64 （glibc） | `x86_64-unknown-linux-gnu` | `@cratestack/cbor-node-linux-x64-gnu` |
| Linux arm64 （glibc） | `aarch64-unknown-linux-gnu` | `@cratestack/cbor-node-linux-arm64-gnu` |
| Linux x64 （musl / Alpine） | `x86_64-unknown-linux-musl` | `@cratestack/cbor-node-linux-x64-musl` |
| Linux arm64 （musl / Alpine） | `aarch64-unknown-linux-musl` | `@cratestack/cbor-node-linux-arm64-musl` |
| Windows x64 | `x86_64-pc-windows-msvc` | `@cratestack/cbor-node-win32-x64-msvc` |

这两个代码都在CI中进行了负载测试，而不仅仅是构建 `build-cbor-node` 肌肉腿跑 它所针对的运行程序体系结构，在上传任何内容之前，加载 `.node` 它只是 下生产 `node:22-alpine` 并通过这个包自己的断言一个固定的编码/解码向量 `native.mjs`． 因此，在x64上勾选“works on Alpine” **和** Arm64，在真正的硬件上，而不是 模拟，在每个版本构建上。

仍然 **不** 覆盖: `win32-arm64`． 也没有wasm/wasi回退-生成的 `native.mjs` 加载程序包含 `wasm32-wasi` 分支，但没有发布 `.wasi.cjs` 或者一个 `@cratestack/cbor-node-wasm32-wasi` 包，以便分支只能添加另一个 `Cannot find module` 到错误链。在不受支持的平台上，加载器会引发泛型 _"找不到本机绑定。NPM有一个与可选依赖相关的bug……”_ 错误, 指责国家预防机制，而不是指出真正的原因； `--no-native-cbor` 是逃生舱口。

上面的每个平台包是一个优化，而不是一个要求：这个包自己的tarball 包每 `.node` 二进制(`files: ["*.node"]`)，加载器会尝试绑定的 `./cratestack-cbor-node.<platform>.node` 之前 `@cratestack/cbor-node-<platform>` 依赖。 子包尚未发布的平台仍然解析工作绑定。

## 常见问题

### @cratestack/cbor-node 是什么？

本机N-API cor编解码器，用于CrateStack生成的TypeScript客户端，封装框架自己的cratstack -codec- cor Rust crate \(crate / cratstack - cor -napi\)，用于与服务器和Rust客户端进行字节相同的连接行为。

### 如何安装 @cratestack/cbor-node？

在项目目录运行 npm install @cratestack/cbor-node，或使用 pnpm add / yarn add / bun add。

### @cratestack/cbor-node 支持 TypeScript 吗？

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

### @cratestack/cbor-node 支持 ESM 还是 CommonJS？

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

### @cratestack/cbor-node 需要什么版本的 Node\.js？

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

### @cratestack/cbor-node 可以商用吗？

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

### @cratestack/cbor-node 还在维护吗？

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