# @cratestack/cbor 中文文档

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

版本：0\.19\.3
npm 元数据更新时间：2026-11-09T16:16:14.400Z
中文译文更新时间：2026-11-10T23:31:22.372Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：14.7 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：3 个
- 首次发布：2026-08-03T07:34:07.798Z
- 最新版本发布：2026-11-09T16:16:14.001Z
- 近 30 天下载量：4224（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

用于CrateStack生成的TypeScript RPC客户端的Umbrella cor编解码：条件导出在Node中自动选择@cratestack/ cor - Node，在浏览器中自动选择@cratestack/ cor -web，在两个平台上使用一个统一的异步createCborCodec() API。

## 安装

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

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

## README

# @ cratestack/ cbor (英语)

一个自发选择右 CBOR 后端的薄伞包 CrateStack 生成的 TypeScript RPC 客户端 : `@cratestack/cbor-node` (# 286, 本地 N- API) 在节点, `@cratestack/cbor-web` (# 287, WASM) 中 : 浏览器 - 1 `npm install`,一个导入路径,环境选择 执行。 最后一块 [285号史诗](https://github.com/cratestack/cratestack/issues/285)。 。 。 .

反应原生相容性证据在 [`docs/react-native-compatibility.md`](https://npmcn.com/package/docs/react-native-compatibility.md)。 。 。 .

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

```ts
import { createCborCodec } from "@cratestack/cbor";

const codec = await createCborCodec();

const bytes = codec.encode({ hello: "world" });
const value = codec.decode(bytes);
```

节点项目从不下载WASM 二进制;浏览器捆绑从不拉 本地语 `.node` 文件——每个平台 `dependencies` (单位:千美元)`@cratestack/cbor-node` 或者说 `@cratestack/cbor-web`) 仅在匹配后实际加载 `exports` 条件解决.

## 自动选择如何运作

这个包裹 `package.json` 声明条件 [`exports`](https://nodejs.org/api/packages.html#conditional-exports) 页:1 联合国 `"."` 条目 :

```json
{
  "exports": {
    ".": {
      "node": { "types": "./dist/node.d.ts", "import": "./dist/node.js" },
      "browser": { "types": "./dist/web.d.ts", "import": "./dist/web.js" },
      "default": { "types": "./dist/web.d.ts", "import": "./dist/web.js" }
    }
  }
}
```

-   节点自己的模块解析器(以及设置 `"node"` 条件——例如Vitest的默认 `environment: "node"`, (中文(简体) ), 网络包装 `target: "node"`选择 `dist/node.js`,用于再出口 `@cratestack/cbor-node`。 。 。 .
-   浏览器目标捆绑器( Vite 客户端构建, Webpack 默认) `web` 目标,下一个客户端捆绑)设置 `"browser"` 条件和选择 `dist/web.js`,用于再出口 `@cratestack/cbor-web`。 。 。 .
-   `"default"` 对既无条件又无条件的解决者来说 在WASM 构建时的分数(`dist/web.js`)),内容更为广泛 两者:只需要 `fetch`编号 :`URL`编号 :`WebAssembly`,所有在每一个 现代JS运行时间(节点、浏览器、边缘/工人运行时间),而 节点建设取决于本地 `.node` 完全无法装入的二进制 在节点外 同样的推理是为什么包级 `"main"`编号 :`"types"` 字段(通过忽略的工具读取) `exports` (完全)也指 瓦斯姆大楼.

## 逃生舱口:显式子路径

有条件 `exports` 分辨率并不完全一致 捆绑商/SR设置——一些安全部门改革框架解决 `"node"` 条件偶数 用于同时向客户端运送的模块(其SSR构建套件) `"node"` 因为代码 _运行_ 服务器渲染时的节点下, 甚至 尽管同样的模块图也被捆绑到浏览器中). 何时 自动解析不满足需要, 导入平台构建 直接 :

```ts
// Force the native Node build, regardless of which condition the
// resolver would otherwise pick:
import { createCborCodec } from "@cratestack/cbor/node";

// Force the WASM build — e.g. from an SSR entry point whose bundler
// resolves "node" but whose output actually needs to run in the browser:
import { createCborCodec } from "@cratestack/cbor/web";
```

两个子路径导出完全相同的 `createCborCodec()` 形状为根 切入点是根入点的 `"node"`编号 :`"browser"` 条件在内部,只是可以直接解决.

## 同步 vs. async: 一个统一的 API

`@cratestack/cbor-node`自己的出口( e)`cborCodec`)是一个平正同步 对象 – 本地的 N- API 模块通过节点同步加载 `require`/ESM相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相相接相接相接相接相接相相相相相相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. `@cratestack/cbor-web`'本身的导出必然是 async (单位:千美元)`createCborCodec(): Promise<CratestackRpcCodec>`)——一次性WASM 即时处理在浏览器中没有同步等效.

此软件包常态化 **两者** 平台到相同的同步构件 形状 : `createCborCodec()` 到处都是,总是回来 `Promise`打开 承诺立即解决的节点(基础代码已经) 装入并同步到模块时 `import` - 这是 完全没有必要的同步仪式 独自一个平台,但它买 单身,真正的平台-不可知的呼叫网站. `await createCborCodec()` 无论哪个条件解决, 行为都一样; 没有任何条件 消耗代码需要分支 环境。 一旦解决,每个 `encode`编号 :`decode` 电话在两个平台上是同步的—— 同步成本, 真实的或名义的, 得到一次准确的报酬.

替代方案——直接暴露平台差异(同步导出) 在节点上,浏览器中的自动合成厂)并记录它——当时 考虑和拒绝:这将会迫使这个伞的每个消费者 包到环境分支或总是 `await` 值为 有时是真正的同步边界,有时不是,它打败了 一个伞包的目的 它应该完全隐藏这种 平台差异.

## 处理错误

错误的 CBOR 输入 `decode`,或一个值 `encode` 无法代表, 扔一个可捕捉的JS `Error` 在两个平台上——见 `@cratestack/cbor-node`还有.. `@cratestack/cbor-web`自己的 README 用于 平台专用机制(国内恐慌对例外的转换对a) (无漏洞的WASM陷阱边界).

## 零处理

两个后端每个 JSON 翻译 `null` (上层或有巢) 真实的 CBOR 无效字节( R)`0xf6`),匹配 `cratestack-codec-cbor`属于自己的 `Option::None` 编码 — 而不是空阵列的突起( e) :`0x80`一些CBOR(美国银行) 后端为光单位类型生产. 见两个平台的软件包 读取详细内容.

## 贡献此软件包( Monorepo- local dev)

此软件包的自建( Q)`tsc`)是纯 TypeScript —— 它不需要一个 Rust 或本姆工具链。 不过它的 `dependencies` 为: `@cratestack/cbor-node` 财务报告和审定财务报表 `@cratestack/cbor-web`{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}这才是问题所在 在这个单曲中,这个包裹 涡轮 `build` 任务故意执行 **没有** 盖起那两个兄弟姐妹 自动( 见 `turbo.json`是因为 `@cratestack/cbor#build` (b) 超载)——a 默认依赖边缘会迫使每个没有工具链的环境 (包括这repo自己的 `js` CI 任务),以编译本地/瓦斯代码 键入一个薄的再出口包装.

实际效果: `pnpm turbo run build test lint --filter='./packages/cratestack-cbor'` 类型检查干净, 并经过任何地方, 但它的节点往返 测试(`tests/node.test.ts`) 只有在 `@cratestack/cbor-node` 实值 _已经_ 已建 — 否则会使用控制台跳过( 不失败) 警告 警告他们 对于真正的覆盖同时发展,先建立兄弟会:

```sh
pnpm turbo run build --filter='./packages/cratestack-cbor-node'
pnpm turbo run build test lint --filter='./packages/cratestack-cbor'
```

或只是运行完整的未过滤 `pnpm turbo run build test lint` 地点 repo root — 将每个软件包建设为自己的顶级目标 所以兄弟姐妹们都在场 测试也在进行 真实的.

## 另见

-   `@cratestack/cbor-node` 节点/本土执行。 内容 README 列出预建的平台; glibc **和穆斯尔** (阿尔卑斯山) Linux x64/arm64 都覆盖在自 第850号箱子后,所以 `createCborCodec()` 下划线 `"node"` 条件不再无法在高山上初始化 基础图像. `win32-arm64` 尸体被发现了.
-   `@cratestack/cbor-web` ——浏览器/WASM执行(wasm-bindgen).
-   `crates/cratestack-codec-cbor` 基本、不变的Rust编码c 这两起执行都结束了.

## 许可证

麻省理工学院

## 常见问题

### @cratestack/cbor 是什么？

用于CrateStack生成的TypeScript RPC客户端的Umbrella cor编解码：条件导出在Node中自动选择@cratestack/ cor - Node，在浏览器中自动选择@cratestack/ cor -web，在两个平台上使用一个统一的异步createCborCodec\(\) API。

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

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

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

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

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

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

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

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

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

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

### @cratestack/cbor 的下载量有多少？

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

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

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