# @capacitor-firebase/storage 中文文档

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

版本：8\.6\.0
npm 元数据更新时间：2026-10-31T07:03:32.550Z
中文译文更新时间：2026-11-09T04:59:44.033Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：207 kB，60 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：firebase ^12\.6\.0，@capacitor/core \>=8\.0\.0
- 首次发布：2023-10-15T13:17:41.107Z
- 最新版本发布：2026-10-31T07:03:32.279Z
- 近 30 天下载量：10931（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 13 个）

## 中文简介

在Android,iOS,和Web上用于Firebase云存储的电容插件.

## 安装

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

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

## README

# 电容器火地库云存储插件

非官方电容插件 [火地云存储](https://firebase.google.com/docs/storage/)\[^1\]

[![Thousands of teams ship faster with Capawesome Cloud Native Builds and Live Updates](https://capawesome.io/assets/banners/cloud-teams-ship-faster-with-capacitor.png)](https://capawesome.io/)

## 使用大小写

Firebase云存储插件通常用于存储和服务用户生成的内容,例如:

-   **用户生成的内容**: 上传由您的用户创建的照片或其他文件到 Cloud 存储.
-   **文件下载**: 将文件下载到Android和iOS或作为本地文件系统 `Blob` 在网络上.
-   **内容交付**: 获取文件的下载 URL 以显示或共享.
-   **文件管理**:在目录中列出文件,读取并更新其元数据,或删除.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 7.x.x (中文(简体) ) | 7.x.x (中文(简体) ) | 折旧 |
| 6.x.x (中文(简体) ) | 6.x.x (中文(简体) ) | 折旧 |

## 指南

-   [使用 Capacitor 的 Firebase 存储上传和管理文件( M)](https://capawesome.io/blog/capacitor-firebase-cloud-storage-guide/): 用此插件上传,下载并管理用户生成的文件.
-   [如何用电容和火把包扎角相机](https://capawesome.io/blog/how-to-wrap-an-angular-app-with-capacitor-and-firebase/): 使用此插件与 Cloud Firestore 并列存储并服务用户加载的文件 .
-   [如何在电容App中使用火把](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/):共享的Firebase设置,以及文件存储如何与数据库和登录对等.

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/storage` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

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

如果您还没有将 Firebase 添加到您的项目中([机器人](https://firebase.google.com/docs/android/setup) 编号 : [iOS系统](https://firebase.google.com/docs/ios/setup)) (中文(简体) ).

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$firebaseStorageVersion` 版本 `com.google.firebase:firebase-storage` (默认 : `22.0.1`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

### iOS系统

#### Swift 软件包管理器

在您的 `capacitor.config.json` (或 `capacitor.config.ts`) 避免 [SwiftPM 软件包识别相撞](https://github.com/capawesome-team/capacitor-firebase/issues/959)数字 :

```json
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/storage": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**请注意**目标 `packageOptions` 支持需要控制器 CLI **8.4.0+ (中文(简体) )**。 。 。 .

## 配置

此插件不需要配置 .

## 演示

这里有一个实例: [robingenz/电容器-火力基地-插座-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## 启动模板

以下启动模板可供使用:

-   [角起火点](https://ionstarter.dev/)

## 使用量

以下例子显示如何上传并下载文件,获得下载URL,列出文件,读取并更新文件元数据,删除文件,并连接到"云存储模拟器".

### 上传文件

上传文件到 Cloud 存储器 。 在Android和iOS上,提供 `uri` 到要上传的文件。 在网络上提供上传数据 `Blob` 使用 `blob` 选项。 随着上传进度和 `completed` 设置为 `true` 上传完成后 :

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const uploadFile = async () => {
  return new Promise((resolve, reject) => {
    FirebaseStorage.uploadFile(
      {
        path: 'images/mountains.png',
        uri: 'file:///var/mobile/Containers/Data/Application/E397A70D-67E4-4258-236E-W1D9E12111D4/Library/Caches/092F8464-DE60-40B3-8A23-EB83160D9F9F/mountains.png',
      },
      (event, error) => {
        if (error) {
          reject(error);
        } else if (event?.completed) {
          resolve();
        }
      }
    );
  });
};
```

### 下载文件

从 Cloud 存储器下载文件 。 在Android和iOS上,文件被下载到本地文件系统,使用 `uri` 选项。 在 Web 上, 下载的文件被返回为 `Blob` 在召回事件中:

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const downloadFileWithFirebaseStorage = async () => {
  return new Promise((resolve, reject) => {
    FirebaseStorage.downloadFile(
      {
        path: 'images/mountains.png',
        uri: 'file:///var/mobile/Containers/Data/Application/E397A70D-67E4-4258-236E-W1D9E12111D4/Library/Caches/mountains.png', // Only available for Android and iOS
      },
      (event, error) => {
        if (error) {
          reject(error);
        } else if (event?.completed) {
          // On Web, the downloaded file is available as a Blob in event.blob
          resolve(event?.blob);
        }
      }
    );
  });
};
```

### 以文件系统插件下载文件

或者,您可以检索文件的下载 URL,并使用官方下载 [电容文件系统](https://capacitorjs.com/docs/apis/filesystem) 插件 :

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';
import { Filesystem, Directory } from '@capacitor/filesystem';

const downloadFileWithFilesystem = async () => {
  const { downloadUrl } = await FirebaseStorage.getDownloadUrl({
    path: 'images/mountains.png',
  });
  const { path } = await Filesystem.downloadFile({
    url: downloadUrl,
    path: 'mountains.png',
    directory: Directory.Cache,
  });
  return path;
};
```

### 获取下载 URL

获取文件的下载 URL, 例如要显示或共享它 :

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const getDownloadUrl = async () => {
  const { downloadUrl } = await FirebaseStorage.getDownloadUrl({
    path: 'images/mountains.png',
  });
  return downloadUrl;
};
```

### 在目录中列出文件

在目录中列出文件 。 使用 `maxResults` 财务报告和审定财务报表 `pageToken` 通过大目录粘接的选项 :

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const listFiles = async () => {
  const { items } = await FirebaseStorage.listFiles({
    path: 'images',
  });
  return items;
};
```

### 读取和更新文件元数据

读取文件的元数据, 如大小、 内容类型和时间戳, 或更新文件, 包括用户定义的自定义元数据 :

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const getMetadata = async () => {
  const result = await FirebaseStorage.getMetadata({
    path: 'images/mountains.png',
  });
  return result;
};

const updateMetadata = async () => {
  await FirebaseStorage.updateMetadata({
    path: 'images/mountains.png',
    metadata: {
      contentType: 'image/png',
      customMetadata: {
        foo: 'bar',
      },
    },
  });
};
```

### 删除文件

删除 Cloud 存储中的文件 :

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const deleteFile = async () => {
  await FirebaseStorage.deleteFile({
    path: 'images/mountains.png',
  });
};
```

### 使用云存储模拟器

开发期间,您可以将您的应用程序装配到本地的"云存储"模拟器上. 当使用Android模拟器设备时, `10.0.2.2` 是连接到 `localhost` 的计算机。 请注意,在Android上,必须允许明确文本的流量,而该流量并非用于生产:

```typescript
import { FirebaseStorage } from '@capacitor-firebase/storage';

const useEmulator = async () => {
  await FirebaseStorage.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};
```

## API 密码

-   [`deleteFile(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-deletefile)
-   [`getDownloadUrl(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-getdownloadurl)
-   [`getMetadata(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-getmetadata)
-   [`listFiles(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-listfiles)
-   [`updateMetadata(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-updatemetadata)
-   [`downloadFile(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-downloadfile)
-   [`uploadFile(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-uploadfile)
-   [`useEmulator(...)`](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-useemulator)
-   [接口](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-type-aliases)

### 删除文件(...)

```typescript
deleteFile(options: DeleteFileOptions) => Promise<void>
```

删除文件 .

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

**自:** 5.3.0 (中文(简体) )

* * *

### 获得下载Url(...)

```typescript
getDownloadUrl(options: GetDownloadUrlOptions) => Promise<GetDownloadUrlResult>
```

获取下载 URL 文件 .

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

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

**自:** 5.3.0 (中文(简体) )

* * *

### 获取气象数据(...)

```typescript
getMetadata(options: GetMetadataOptions) => Promise<GetMetadataResult>
```

获取文件的元数据 .

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

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

**自:** 5.3.0 (中文(简体) )

* * *

### 列表 Files (...)

```typescript
listFiles(options: ListFilesOptions) => Promise<ListFilesResult>
```

在目录中列出文件 .

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

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

**自:** 5.3.0 (中文(简体) )

* * *

### 更新Metadata (...)

```typescript
updateMetadata(options: UpdateMetadataOptions) => Promise<void>
```

更新一个文件的元数据 .

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

**自:** 5.3.0 (中文(简体) )

* * *

### 下载文件(...)

```typescript
downloadFile(options: DownloadFileOptions, callback: DownloadFileCallback) => Promise<CallbackId>
```

下载文件 .

打开 **机器人** 财务报告和审定财务报表 **iOS系统**,文件下载到本地文件系统 使用 `uri` 选项.

打开 **网页**,文件被下载为 `Blob` 并返回到 调用事件 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DownloadFileOptions](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-downloadfileoptions)` |
| **`callback`** | `[DownloadFileCallback](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-downloadfilecallback)` |

**回返情况:** `Promise<string>`

**自:** 8.2.0 (中文(简体) )

* * *

### 上传文件(...)

```typescript
uploadFile(options: UploadFileOptions, callback: UploadFileCallback) => Promise<CallbackId>
```

上传文件 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[UploadFileOptions](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-uploadfileoptions)` |
| **`callback`** | `[UploadFileCallback](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-uploadfilecallback)` |

**回返情况:** `Promise<string>`

**自:** 5.3.0 (中文(简体) )

* * *

### 使用计算器(...)

```typescript
useEmulator(options: UseEmulatorOptions) => Promise<void>
```

您的应用程序可以和云存储模拟器交谈.

在Android上,必须允许明确文本的流量. 关于电容配置 :

```
{
  server: {
    cleartext: true
  }
}
```

**明确文本流量并非用于生产.**

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

**自:** 6.1.0 (中文(简体) )

* * *

### 接口

#### 删除文件选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 要删除的文件的完整路径, 包括文件名 . | 5.3.0 (中文(简体) ) |

#### 获取下载Url Result

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`downloadUrl`** | `string` | 文件下载url. | 5.3.0 (中文(简体) ) |

#### 获取下载

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 获取下载url的完整文件路径,包括文件名. | 5.3.0 (中文(简体) ) |

#### 获取元数据结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`bucket`** | `string` | 此文件包含的桶. | 5.3.0 (中文(简体) ) |
| **`createdAt`** | `number` | 文件创建时间戳自纪元后为毫秒. | 5.3.0 (中文(简体) ) |
| **`generation`** | `string` | 物之相传. | 5.3.0 (中文(简体) ) |
| **`md5Hash`** | `string` | 文件的md5散列. | 5.3.0 (中文(简体) ) |
| **`metadataGeneration`** | `string` | 对象元数据生成. | 5.3.0 (中文(简体) ) |
| **`name`** | `string` | 此文件的短名, 是完整路径的最后一个组件 . | 5.3.0 (中文(简体) ) |
| **`path`** | `string` | 文件的完整路径,包括文件名. | 5.3.0 (中文(简体) ) |
| **`size`** | `number` | 以字节表示的文件大小 . | 5.3.0 (中文(简体) ) |
| **`updatedAt`** | `number` | 文件自纪元以来最后一次以毫秒更新的时间戳 . | 5.3.0 (中文(简体) ) |
| **`cacheControl`** | `string` | 担任 `Cache-Control` 对象下载时的标题 . | 6.1.0 (中文(简体) ) |
| **`contentDisposition`** | `string` | 担任 `Content-Disposition` 对象下载时的标题 . | 6.1.0 (中文(简体) ) |
| **`contentEncoding`** | `string` | 担任 `Content-Encoding` 对象下载时的标题 . | 6.1.0 (中文(简体) ) |
| **`contentLanguage`** | `string` | 担任 `Content-Language` 对象下载时的标题 . | 6.1.0 (中文(简体) ) |
| **`contentType`** | `string` | 担任 `Content-Type` 对象下载时的标题 . | 6.1.0 (中文(简体) ) |
| **`customMetadata`** | `{ [key: string]: string; }` | 额外的用户定义自定义元数据 . | 6.1.0 (中文(简体) ) |

#### 获取气象数据选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 获取元数据的完整文件路径,包括文件名. | 5.3.0 (中文(简体) ) |

#### 列表文件夹

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`items`** | `StorageReference[]` | 目录中的文件列表 . | 5.3.0 (中文(简体) ) |
| **`nextPageToken`** | `string` | 如果设定了,此列表可能会有更多的结果. 使用此符号恢复列表 . | 5.3.0 (中文(简体) ) |

#### 存储参考

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`bucket`** | `string` | 此文件包含的桶. | 5.3.0 (中文(简体) ) |
| **`path`** | `string` | 文件的完整路径,包括文件名. | 5.3.0 (中文(简体) ) |
| **`name`** | `string` | 此文件的短名, 是完整路径的最后一个组件 . | 5.3.0 (中文(简体) ) |

#### 列表文件选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`path`** | `string` | 列出文件的目录的完整路径 . |  | 5.3.0 (中文(简体) ) |
| **`maxResults`** | `number` | 要返回的最大结果数 . | `1000` | 5.3.0 (中文(简体) ) |
| **`pageToken`** | `string` | 页面符号,通过先前调用此方法返回 。 如果提供,则从原职位恢复列名. |  | 5.3.0 (中文(简体) ) |

#### 更新元数据选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 用于更新元数据的完整文件路径,包括文件名. | 5.3.0 (中文(简体) ) |
| **`metadata`** | `[SettableMetadata](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-settablemetadata)` | 要更新的元数据. | 5.3.0 (中文(简体) ) |

#### 设置元数据

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`cacheControl`** | `string` | 担任 `Cache-Control` 对象下载时的标题 . | 5.3.0 (中文(简体) ) |
| **`contentDisposition`** | `string` | 担任 `Content-Disposition` 对象下载时的标题 . | 5.3.0 (中文(简体) ) |
| **`contentEncoding`** | `string` | 担任 `Content-Encoding` 对象下载时的标题 . | 5.3.0 (中文(简体) ) |
| **`contentLanguage`** | `string` | 担任 `Content-Language` 对象下载时的标题 . | 5.3.0 (中文(简体) ) |
| **`contentType`** | `string` | 担任 `Content-Type` 对象下载时的标题 . | 5.3.0 (中文(简体) ) |
| **`customMetadata`** | `{ [key: string]: string; }` | 额外的用户定义自定义元数据 . | 5.3.0 (中文(简体) ) |

#### 下载文件选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 要下载的文件的完整路径, 包括文件名 . | 8.2.0 (中文(简体) ) |
| **`uri`** | `string` | 将文件下载到的uri 。 仅供Android和iOS使用. | 8.2.0 (中文(简体) ) |

#### 下载文件CallbackEvent

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`progress`** | `number` | 下载进度,在0到1之间的百分比. | 8.2.0 (中文(简体) ) |
| **`bytesTransferred`** | `number` | 已转移的字节数 。 仅供Android和Web使用. | 8.2.0 (中文(简体) ) |
| **`totalBytes`** | `number` | 要转移的字节总数 。 仅供Android和Web使用. | 8.2.0 (中文(简体) ) |
| **`completed`** | `boolean` | 下载是否完成 . | 8.2.0 (中文(简体) ) |
| **`blob`** | `Blob` | 下载文件为 Blob 。 仅供Web使用. | 8.2.0 (中文(简体) ) |

#### 上传文件选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`blob`** | `Blob` | 要上传的数据 。 仅供Web使用. | 5.3.0 (中文(简体) ) |
| **`path`** | `string` | 应当上传数据的完整路径,包括文件名. | 5.3.0 (中文(简体) ) |
| **`uri`** | `string` | 要上传的 UR 到文件 。 仅供Android和iOS使用. | 5.3.0 (中文(简体) ) |
| **`metadata`** | `[UploadMetadata](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-uploadmetadata)` | 要设置文件的元数据 . | 5.4.0 (单位:千美元) |

#### 上传元数据

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`md5Hash`** | `string` | 文件的基础64-编码为MD5散列. 仅供Web使用. | 5.4.0 (单位:千美元) |

#### 上传文件CallbackEvent

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`progress`** | `number` | 上传进度,在0到1之间的百分比. | 5.3.0 (中文(简体) ) |
| **`bytesTransferred`** | `number` | 已转移的字节数 。 仅供Android和Web使用. | 5.3.0 (中文(简体) ) |
| **`totalBytes`** | `number` | 要转移的字节总数 。 仅供Android和Web使用. | 5.3.0 (中文(简体) ) |
| **`completed`** | `boolean` | 上传是否完成 . | 5.3.0 (中文(简体) ) |

#### 使用编辑器选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`host`** | `string` | 模拟器主机没有任何端口或方案. 使用Android模拟器设备时注意: 10.0.2.2是连接主机计算机"localhost"的特殊IP地址. |  | 6.1.0 (中文(简体) ) |
| **`port`** | `number` | 模拟器端口 . | `9199` | 6.1.0 (中文(简体) ) |

### 类型异名

#### 下载回调文件

`(event: [DownloadFileCallbackEvent](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-downloadfilecallbackevent) | null, error: any): void`

#### 调用文件夹

`string`

#### 上传FileCallback

`(event: [UploadFileCallbackEvent](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-uploadfilecallbackevent) | null, error: any): void`

## 财务问题

### 我如何追踪上传或下载的进展?

这个 `uploadFile(...)` 财务报告和审定财务报表 `downloadFile(...)` 方法接受一个以包含 `progress` 作为0至1和a之间的分数 `completed` 旗帜。 这个 `bytesTransferred` 财务报告和审定财务报表 `totalBytes` 属性仅在Android和Web上可用.

### 不同平台对文件的下载有何不同?

在Android和iOS上,文件被下载到本地文件系统,使用 `uri` 选项。 在 Web 上, 下载的文件被返回为 `Blob` 在召回活动中。 或者,您可以用 `getDownloadUrl(...)` 并使用 Capacitor 文件系统插件下载文件,如 [使用示例](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-download-a-file-with-the-filesystem-plugin) 见上文.

### 我该如何上传用户选择的文件 ?

在Android和iOS上,通过 `uri` 打开 `uploadFile(...)` 方法。 在网络上,通过数据作为 `Blob` 使用 `blob` 选项。 你可以用这个 [文件拾取器](https://capawesome.io/docs/sdks/capacitor/file-picker/) 让用户在设备上选择文件的插件.

### 我如何存储关于文件的额外信息?

您可以在上传文件时为它设置元数据 `metadata` 选项或稍后更新 `updateMetadata(...)`,包括通过 `customMetadata`启用 `getMetadata(...)` 以读取文件的元数据,例如其大小、内容类型和时间戳.

### 我能测试一下云存储模拟器吗?

是的,用那个 `useEmulator(...)` 将您的应用程序装配到本地 Cloud 存储模拟器上的方法, 如 [使用示例](https://npmcn.com/package/%40capacitor-firebase/storage/#readme-use-the-cloud-storage-emulator) 页:1 在Android模拟器设备上测试时,请使用 `10.0.2.2` 作为到达 `localhost` 的计算机。 记住,在Android上,必须允许清晰文本的流量,这并非用于生产.

## 相关插件

-   [文件拾取器](https://capawesome.io/docs/sdks/capacitor/file-picker/):让用户从设备中选择文件,目录,图像,或视频.
-   [文件压缩器](https://capawesome.io/docs/sdks/capacitor/file-compressor/):在上传前压缩PNG,JPEG等文件和WebP图像.
-   [火地云炉](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/): Cloud Firestore中存储并同步应用数据.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/storage/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/storage/LICENSE)。 。 。 .

\[^1\]: 这个项目不附属于Google LLC或其任何子公司或子公司,也不获得其认可、支持、赞助或批准.

## 常见问题

### @capacitor-firebase/storage 是什么？

在Android,iOS,和Web上用于Firebase云存储的电容插件\.

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

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

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

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

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

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

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

@capacitor-firebase/storage 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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