# @capacitor/storage 中文文档

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

版本：1\.2\.5
npm 元数据更新时间：2026-09-28T18:17:52.813Z
中文译文更新时间：2026-11-09T04:28:32.054Z
软件包许可：MIT

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

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

弃用说明：package has been renamed to @capacitor/preferences

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

- 包体积（解压后）：76.7 kB，29 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core ^3\.0\.0
- 首次发布：2020-09-01T01:56:34.005Z
- 最新版本发布：2022-03-03T18:24:46.044Z
- 近 30 天下载量：21907（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 0 个）

## 中文简介

存储API为轻量级数据提供了一个简单的密钥/值持续存储.

## 安装

```sh
npm install @capacitor/storage
```

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

## README

# @ 电容器/ 存储器

存储API为轻量级数据提供了一个简单的密钥/值持续存储.

移动操作系统可定期清除下列数据: `window.localStorage`,所以这个 应使用API。 此 API 将返回使用 `localStorage` 当运行为进步Web App.

此插件将使用 [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults) 在iOS和 [`SharedPreferences`](https://developer.android.com/reference/android/content/SharedPreferences) 安卓号 如果应用程序未安装, 则清除存储数据 .

**说明**: 这个 API 是 _没有_ 打算用作本地数据库。 如果你的应用 存储大量数据,有高读/写负载,或需要复杂的查询, 我们建议看看基于SQLite的解决方案. 这种解决办法之一是: [离子安全存储](https://ionic.io/docs/secure-storage),一个基于 SQLite 的引擎,具有全加密支持. 这个 [社区](https://github.com/capacitor-community/) 还建造了多台其他存储引擎.

## 安装

```bash
npm install @capacitor/storage
npx cap sync
```

## 示例

```typescript
import { Storage } from '@capacitor/storage';

const setName = async () => {
  await Storage.set({
    key: 'name',
    value: 'Max',
  });
};

const checkName = async () => {
  const { value } = await Storage.get({ key: 'name' });

  console.log(`Hello ${value}!`);
};

const removeName = async () => {
  await Storage.remove({ key: 'name' });
};
```

## 与JSON合作

存储 API 只支持字符串值 。 不过,如果你 `JSON.stringify` 调用前的对象 `set()`,则 `JSON.parse` 从 `get()`。 。 。 .

这种方法也可用于存储非字符串值,例如数字和布尔.

## API 密码

-   [`configure(...)`](https://npmcn.com/package/%40capacitor/storage/#readme-configure)
-   [`get(...)`](https://npmcn.com/package/%40capacitor/storage/#readme-get)
-   [`set(...)`](https://npmcn.com/package/%40capacitor/storage/#readme-set)
-   [`remove(...)`](https://npmcn.com/package/%40capacitor/storage/#readme-remove)
-   [`clear()`](https://npmcn.com/package/%40capacitor/storage/#readme-clear)
-   [`keys()`](https://npmcn.com/package/%40capacitor/storage/#readme-keys)
-   [`migrate()`](https://npmcn.com/package/%40capacitor/storage/#readme-migrate)
-   [`removeOld()`](https://npmcn.com/package/%40capacitor/storage/#readme-removeold)
-   [接口](https://npmcn.com/package/%40capacitor/storage/#readme-interfaces)

### 配置(...)

```typescript
configure(options: ConfigureOptions) => Promise<void>
```

在运行时配置存储插件 .

选项 `undefined` 将不使用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ConfigureOptions](https://npmcn.com/package/%40capacitor/storage/#readme-configureoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 获取(...)

```typescript
get(options: GetOptions) => Promise<GetResult>
```

从给定密钥的存储中获取值 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetOptions](https://npmcn.com/package/%40capacitor/storage/#readme-getoptions)` |

**回返情况:** `Promise<[GetResult](https://npmcn.com/package/%40capacitor/storage/#readme-getresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 设置(...)

```typescript
set(options: SetOptions) => Promise<void>
```

为给定的密钥设置存储值 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetOptions](https://npmcn.com/package/%40capacitor/storage/#readme-setoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 删除(...)

```typescript
remove(options: RemoveOptions) => Promise<void>
```

删除给定密钥存储中的值( 如果有 ) .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RemoveOptions](https://npmcn.com/package/%40capacitor/storage/#readme-removeoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 清除( c)

```typescript
clear() => Promise<void>
```

从存储中清除密钥和值 .

**自:** 1.0.0 (单位:千美元)

* * *

### 键( )

```typescript
keys() => Promise<KeysResult>
```

返回存储中的已知密钥列表 .

**回返情况:** `Promise<[KeysResult](https://npmcn.com/package/%40capacitor/storage/#readme-keysresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 迁移( )

```typescript
migrate() => Promise<MigrateResult>
```

从 Capacitor 2 存储插件迁移数据.

这一行动是无损的。 它不会删除旧数据,只会 如果密钥尚未设置, 请写入新数据 . 要删除迁移后的旧数据, 请调用 removeOld () .

**回返情况:** `Promise<[MigrateResult](https://npmcn.com/package/%40capacitor/storage/#readme-migrateresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 删除旧( C)

```typescript
removeOld() => Promise<void>
```

删除旧数据 `_cap_` 前缀来自 Capacitor 2 存储插件.

**自:** 1.1.0 国家

* * *

### 接口

#### 配置选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`group`** | `string` | 设置存储组 。 存储组用于组织密钥/值对. 使用“ NativeStorage ” 值提供反向兼容性 [`cordova-plugin-nativestorage`](https://www.npmjs.com/package/cordova-plugin-nativestorage)警告: `clear()` 方法可以在使用 “ NativeStorage” 组时删除意外值. | `CapacitorStorage` | 1.0.0 (单位:千美元) |

#### 获取恢复

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`value`** | `string | null` | 与给定密钥相关的存储值 。 如果一个值之前没有设定或被删除,则该值将是 `null`。 。 。 . | 1.0.0 (单位:千美元) |

#### 获取选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 从存储取回值的密钥 . | 1.0.0 (单位:千美元) |

#### 设置选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 与存储中设置的值关联的密钥 . | 1.0.0 (单位:千美元) |
| **`value`** | `string` | 使用相关密钥设置的值 . | 1.0.0 (单位:千美元) |

#### 删除选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 从存储中删除值的密钥 . | 1.0.0 (单位:千美元) |

#### 密钥结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`keys`** | `string[]` | 已知存储的密钥 . | 1.0.0 (单位:千美元) |

#### 迁移结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`migrated`** | `string[]` | 已迁移的一系列密钥 . | 1.0.0 (单位:千美元) |
| **`existing`** | `string[]` | 在 Capacitor 2 存储插件中具有值的已迁移或以其他方式存在于存储中的密钥数组 . | 1.0.0 (单位:千美元) |

## 常见问题

### @capacitor/storage 是什么？

存储API为轻量级数据提供了一个简单的密钥/值持续存储\.注意：该包已被作者标记为弃用——package has been renamed to @capacitor/preferences

### 如何安装 @capacitor/storage？

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

### @capacitor/storage 支持 TypeScript 吗？

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

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

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

### @capacitor/storage 可以商用吗？

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

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

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

### @capacitor/storage 还在维护吗？

最新版本 1\.2\.5 发布于 2022/03/04（4 年前）；至今共发布 29 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/09/01。作者已将其标记为弃用，新项目建议寻找替代方案。