# @aparajita/capacitor-secure-storage 中文文档

规范地址：https://npmcn.com/package/%40aparajita/capacitor-secure-storage/

版本：8\.0\.1
npm 元数据更新时间：2026-09-23T03:52:59.194Z
中文译文更新时间：2026-11-06T08:53:32.892Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aparajita/capacitor-secure-storage
原文对照：https://npmcn.com/package/%40aparajita/capacitor-secure-storage/?lang=original
源码仓库：https://github.com/aparajita/capacitor-secure-storage

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

- 包体积（解压后）：96.4 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：5 个
- 首次发布：2021-03-26T17:38:01.316Z
- 最新版本发布：2026-09-23T03:52:59.011Z
- 近 30 天下载量：1588200（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 2 个）

## 中文简介

为iOS 和 Android 提供安全存储的 Capacitor 8+ 插件

## 安装

```sh
npm install @aparajita/capacitor-secure-storage
```

也可以使用：`pnpm add @aparajita/capacitor-secure-storage`、`yarn add @aparajita/capacitor-secure-storage`、`bun add @aparajita/capacitor-secure-storage`

## README

# 电容器安全存储器  [![npm version](https://badge.fury.io/js/@aparajita%2Fcapacitor-secure-storage.svg)](https://badge.fury.io/js/@aparajita%2Fcapacitor-secure-storage)

此插件用于 [电容 8](https://capacitorjs.com/) 提供iOS和Android的安全密钥/值存储. 它最初的设计是作为同伴 [@aparajita/ 电容- 生物测量- 原子](https://github.com/aparajita/capacitor-biometric-auth/#readme) 为了安全地存储登录证书,但可用于存储任何JSON数据类型.

🛑 **打破变化:**

见 [控制器 8 支持页面](https://capacitorjs.com/docs/main/reference/support-policy) 用于了解对最低限度支持的发展工具和平台的修改情况.

## 安装

```sh
pnpm add @aparajita/capacitor-secure-storage # npm install, yarn add
```

没有使用 [小时](https://pnpm.io/)你欠它自己 一个尝试。 更快速、更适合单簧管 _就是这样,就是这样_ 磁盘空间比其它选项少.

## 使用量

API 完整记录 [这里](https://npmcn.com/package/%40aparajita/capacitor-secure-storage/src/definitions.ts)。关于在实践中如何使用此插件的完整实例,请参见 [演示区域](https://npmcn.com/package/%40aparajita/capacitor-secure-storage/#readme-demo)。 。 。 .

### iOS系统

在iOS上,数据被存储在加密的系统密钥链中,并且是您的应用程序所特有的. 请注意,目前iOS将 **没有** 删除应用程序的密钥链数据 。 但由于只有具有相同应用id的应用程序——苹果公司保证在所有应用中都是独一无二的——才能访问该数据,所以这不是一个安全问题.

#### iCloud 密钥链同步

您可以与 iCloud 键链同步数据 。 同步可以在全球和每个操作中进行控制. 这使得您可以在多个设备中共享同一应用程序的安全数据(例如登录证书).

> QQ 用户必须启用设备上的 iCloud 密钥链, 以便数据同步 .

要打开或关闭全球同步,请打电话 `setSynchronize()`。您可以通过在 `sync` 选项.

注意:iOS将本地键链和iCloud键链视为两个独立的键链. 哪个键链受到操作的影响取决于全球和每个操作同步设置. 这意味着,例如,一个值可以用两个键链中相同的键来存储和取回.

> 当解析同步设置为真时, 呼叫到 `keys()` 返回密钥 **两者** iCloud和本地密钥链。 因此可能会出现重复.

### 机器人

在Android上,数据在GCM模式下使用AES加密,使用由Android KeyStore所生成的秘密密钥,再被存储在"共享优先级"中,该密钥是您的应用程序所特有的. 如果该应用被删除,其数据也被删除.

### 网页

在网络上存储数据 **未加密** 内 `localStorage`,这样您就可以看到您存储的数据。 这只用于调试目的; 生产时不应在网络上使用此插件 .

## 演示

Ionic/Vue 演示应用演示了这个插件的所有特性. 演示有两种变体,一种使用可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可口可 当然,CocoaPods和Swift软件包管理器只应用于iOS. 在两种演示中,Android版本是相同的.

### 安装

[小时](https://pnpm.io/) 需要运行演示.

```shell
# Clone the github repo and install dependencies
git clone https://github.com/aparajita/capacitor-secure-storage.git
cd capacitor-secure-storage
pnpm install -r
```

### 运行

在运行其中任一演示之前, 您必须先构建插件, 因为演示参考了插件的本地构造 .

```shell
pnpm build
```

从根目录中可以使用:

iOS: (英语)

```shell
pnpm demo.pods.ios
pnpm demo.spm.ios
```

机器人:

```shell
pnpm demo.pods.android
pnpm demo.spm.android
```

网络 :

```shell
pnpm demo.pods.browser
pnpm demo.spm.browser
```

您也可以在演示目录中运行命令 :

```shell
cd demo-pods # or cd demo-spm
pnpm ios
pnpm android
pnpm dev
```

### 使用量

#### 同步到 iCloud 密钥链( 只有iOS)

在iOS上,出现了“iCloud同步”复选框。 打开/关闭 iCloud 同步系统.

此外,控制了iCloud同步的“关键”字段右侧出现了“同步”复选框。 默认情况下,它处于不确定状态,这意味着使用了全局同步设置. 将“ 同步” 复选框周期在未确定 {} 检查\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 如果检查或未选中“同步”复选框,则该复选框将覆盖全局同步复选框.

当解析同步设置启动时,任何操作(除设置前缀外)都会影响iCloud键链而不是本地键链.

#### 设置前缀

要更改密钥前缀,请编辑"前缀"字段并按"Set".

#### 保存一个值

要保存要存储的密钥/值项,请在"Key"字段中输入密钥,在"Data"字段中输入JSON-parseable值. 当您在“数据”字段中输入时,如果它是有效的值,则数据类型显示在字段下方.

您可以存储任何有效的 JSON 值: 字符串、 数字、 布尔、 数组、 对象或无效 。 此外,如果"数据"字段看起来像ISO 8601日期时间(从YYYY-MM-DD开始),它被解析成这样,如果成功解析该类型将显示为"日期". 注意时间和毫秒是可选的. 因此,例如,这些都被解析为一个有效的日期:

```
2020-08-27
2020-08-27T13:27:07
2020-08-27T13:27:07.413Z
```

#### 获得一个值

要从存储中获取值,请输入密钥并按"Get".

#### 删除项目

要删除存储中的项目, 请输入密钥并按" Remove" 键.

#### 清除所有项目

要从存储中移除所有带有当前前缀的项目,请按"Clear".

#### 查看全部密钥

要查看存储中所有带有当前前缀的键,请按"键". 注意,如果解析的同步设置在iOS上是真实的,则密钥来自 **两者** 将显示 iCloud 密钥链和本地密钥链.

## 常见问题

### @aparajita/capacitor-secure-storage 是什么？

为iOS 和 Android 提供安全存储的 Capacitor 8\+ 插件

### 如何安装 @aparajita/capacitor-secure-storage？

在项目目录运行 npm install @aparajita/capacitor-secure-storage，或使用 pnpm add / yarn add / bun add。

### @aparajita/capacitor-secure-storage 支持 TypeScript 吗？

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

### @aparajita/capacitor-secure-storage 支持 ESM 还是 CommonJS？

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

### @aparajita/capacitor-secure-storage 需要什么版本的 Node\.js？

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

### @aparajita/capacitor-secure-storage 可以商用吗？

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

### @aparajita/capacitor-secure-storage 的下载量有多少？

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

### @aparajita/capacitor-secure-storage 还在维护吗？

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