# @ecies/ciphers 中文文档

规范地址：https://npmcn.com/package/%40ecies/ciphers/

版本：0\.2\.6
npm 元数据更新时间：2026-03-31T18:16:21.576Z
中文译文更新时间：2026-11-13T05:07:34.748Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ecies/ciphers
原文对照：https://npmcn.com/package/%40ecies/ciphers/?lang=original
项目主页：https://github.com/ecies/js-ciphers#readme
源码仓库：https://github.com/ecies/js-ciphers

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

- 包体积（解压后）：16.2 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：0 个
- peer 依赖：@noble/ciphers ^1\.0\.0
- 首次发布：2024-10-11T17:48:44.260Z
- 最新版本发布：2026-03-31T18:16:21.279Z
- 近 30 天下载量：58032168（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 1 个）

## 中文简介

节点/ Pure JavaScript 对称密码适配器

## 安装

```sh
npm install @ecies/ciphers
```

也可以使用：`pnpm add @ecies/ciphers`、`yarn add @ecies/ciphers`、`bun add @ecies/ciphers`

## README

# @ecies/密码

[![License](https://img.shields.io/github/license/ecies/js-ciphers.svg)](https://github.com/ecies/js-ciphers) [![NPM Package](https://img.shields.io/npm/v/@ecies/ciphers.svg)](https://www.npmjs.com/package/@ecies/ciphers) [![NPM Downloads](https://img.shields.io/npm/dm/@ecies/ciphers)](https://npm-stat.link/@ecies/ciphers) [![Install size](https://packagephobia.com/badge?p=@ecies/ciphers)](https://packagephobia.com/result?p=@ecies/ciphers) [![CI](https://img.shields.io/github/actions/workflow/status/ecies/js-ciphers/ci.yml)](https://github.com/ecies/js-ciphers/actions) [![Codecov](https://img.shields.io/codecov/c/github/ecies/js-ciphers.svg)](https://codecov.io/gh/ecies/js-ciphers)

节点/Pure JavaScript对称密码适配器.

如果一些平台(如节点、德诺、包子)有本地执行,它就会使用 [`node:crypto`](https://nodejs.org/api/crypto.html#cryptocreatecipherivalgorithm-key-iv-options) 提高效率.

否则(例如浏览器,反应原生),它将使用 [`@noble/ciphers`](https://github.com/paulmillr/noble-ciphers) 用于兼容性.

|  | 爱斯 | 恰克语name |
| --- | --- | --- |
| 节点 | `node:crypto` ⚡ | `node:crypto` ⚡ |
| 阿宝 | `node:crypto` ⚡ | `@noble/ciphers` |
| 德诺 | `node:crypto` ⚡ | `node:crypto` ⚡ |
| 浏览器 | `@noble/ciphers` | `@noble/ciphers` |
| 原生反应 | `@noble/ciphers` | `@noble/ciphers` |

> \[注\] 您可能需要多填充 [`crypto.getRandomValues`](https://github.com/LinusU/react-native-get-random-values) 反应原生.
> 
> 有些限制,你看 [已知的限制](https://npmcn.com/package/%40ecies/ciphers/#readme-known-limitations) 见下文.
> 
> 这个库是可树摇动的,未使用的代码会被捆绑者排除在外.

检查 [实例](https://npmcn.com/package/%40ecies/ciphers/example/) 用于更多用途的文件夹.

## 快开始

```js
// example/quick-start.js
import { aes256gcm } from "@ecies/ciphers/aes";
import { randomBytes } from "@noble/ciphers/webcrypto";

const TEXT = "hello world🌍!";
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const msg = encoder.encode(TEXT);

const key = randomBytes();
const nonce = randomBytes(16);
const cipher = aes256gcm(key, nonce);
console.log("decrypted:", decoder.decode(cipher.decrypt(cipher.encrypt(msg))));
```

API跟着 `@noble/ciphers`方便使用的API,你可以检查它们 [实例](https://github.com/paulmillr/noble-ciphers#examples) 还有.

## 支持的密码

-   `aes-256-gcm`
    -   16个字节和12个字节nice都得到了支持.
-   `aes-256-cbc`
    -   **仅用于遗留应用程序**。您应当使用 `xchacha20-poly1305` 或者说 `aes-256-gcm` 尽可能.
    -   诺斯总是16字节.
-   `chacha20-poly1305`
    -   农斯总是12字节.
-   `xchacha20-poly1305`
    -   农斯总是24字节.

如果密钥是固定的,而非斯小于16字节, **避免随机生成非ce**。 。 。 .

## 已知的限制

-   `xchacha20-poly1305` 与纯粹的联署材料一起实施 [`hchacha20`](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha#section-2.2) 函数和 `node:crypto`是因为 `chacha20-poly1305` 节点/节点.
-   目前(2026年4月), `node:crypto`是因为 `chacha20-poly1305` 不支持关于 [包头](https://github.com/oven-sh/bun/issues/8072), (中文(简体) ), `@noble/ciphers`其执行被使用。 从德诺 2.7.10, `node:crypto`是因为 `chacha20-poly1305` 实值 [支持](https://github.com/denoland/deno/issues/28411)。请升级 deno, 以便使用本地执行来提高绩效.
-   一些旧版本的 `deno` [不支持](https://github.com/denoland/deno/discussions/17964#discussioncomment-10917259) **间接** 有条件出口。 例如,如果一个库使用 `@ecies/ciphers`该图书馆的客户端代码可能回落到 `node:crypto` 执行《公约》的情况,特别是 `aes-256-gcm` 财务报告和审定财务报表 `chacha20-poly1305`。如果你发现这样的问题,请升级 deno 并运行 `--conditions deno` (>= 2.4.0)或 `--unstable-node-conditions deno`(>=2.3.6,<2.4.0\].

## 常见问题

### @ecies/ciphers 是什么？

节点/ Pure JavaScript 对称密码适配器

### 如何安装 @ecies/ciphers？

在项目目录运行 npm install @ecies/ciphers，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@noble/ciphers（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ecies/ciphers 支持 TypeScript 吗？

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

### @ecies/ciphers 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ecies/ciphers 需要什么版本的 Node\.js？

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

### @ecies/ciphers 可以商用吗？

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

### @ecies/ciphers 的下载量有多少？

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

### @ecies/ciphers 还在维护吗？

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