# @capgo/capacitor-uploader 中文文档

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

版本：8\.3\.27
npm 元数据更新时间：2026-11-09T07:45:05.014Z
中文译文更新时间：2026-11-09T02:36:24.849Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-uploader
原文对照：https://npmcn.com/package/%40capgo/capacitor-uploader/?lang=original
项目主页：https://capgo.app/docs/plugins/uploader/
源码仓库：https://github.com/Cap-go/capacitor-uploader

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

- 包体积（解压后）：218 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2024-09-03T20:32:44.730Z
- 最新版本发布：2026-11-09T07:45:04.700Z
- 近 30 天下载量：92186（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：129（近 12 个月 79 个）

## 中文简介

本地上传文件

## 安装

```sh
npm install @capgo/capacitor-uploader
```

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

## README

# @ capgo/ 电容器加载器

从您的 Capacitor app 上传文件, 并带有本地背景上传, 程序关闭后继续运行, 并进行进度事件和重试 .

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-uploader)](https://capgo.app/?ref=plugin_uploader)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_uploader)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_uploader) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-uploader` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/电容-uploader到我的电容软件上并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_uploader) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_uploader)

![@capgo/capacitor-uploader for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-uploader/main/assets/github-social-preview.png)

## 主要特点

-   **上传**数字 : `startUpload()` 发送文件与 `PUT` 或者说 `POST`,自定义标题和参数.
-   **多块**数字 : `uploadMultipart()` 发送文件为 `multipart/form-data`。 。 。 .
-   **进展活动**页:1 `events` 听者报告进展、完成和出错.
-   **控制权**数字 : `removeUpload()` 取消上传, `maxRetries` 重复失败.
-   **背景情况**: 背景情况 `URLSession` 在iOS和上传服务 并通知Android.
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 网络上传 `fetch()` 在页面打开时,没有本地背景上传.

## 上传插件

这个插件提供了一个灵活的方法,可以将本地文件上传到各种服务器上,包括带有预先签名的URL的S3.

可用于与 [电容相机预览](https://github.com/Cap-go/camera-preview) 以可靠的方式上传文件,而不是在网络视图的缓冲器中阅读,然后在JS中上传.

在网络上,文件路径支持使用以下格式的索引DB(IDB)语义路径:  
`idb://[database-name]/[collection-name]/[key]`  
这允许与索引DB进行无缝集成,用于存储和检索文件.

## 文档

这里有最完整的医生: [页:1](https://capgo.app/docs/plugins/uploader/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-uploader` plugin in my project.
```

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

```bash
npm install @capgo/capacitor-uploader
npx cap sync
```

## 机器人

在您的 `AndroidManifest.xml` 文件 :

```xml
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
```

## iOS系统

在iOS上,插件通过背景上传 `URLSession` 使用标识符 `CapacitorUploaderBackgroundSession`。 。 。 .

上传工作往往没有额外内容 `Info.plist` 键。 为了让系统在背景传输完成时唤醒您的应用,请添加 `fetch` 背景模式 :

```xml
<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
</array>
```

执行 **没有** 添加 `processing` 仅此插件的背景模式。 需要 App Store 连接 `BGTaskSchedulerPermittedIdentifiers` 任何时候 `processing` 声明,此插件不注册 `BGTaskScheduler` 任务。 如果您的应用程序已经包含 `processing` (例如,来自旧文件)和验证失败,加上:

```xml
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>CapacitorUploaderBackgroundSession</string>
</array>
```

见 [问题115](https://github.com/Cap-go/capacitor-uploader/issues/115) 用于上下文.

## 示例 S3 上传

```typescript
import { Uploader } from '@capgo/capacitor-uploader';

async function uploadToS3(filePath: string, presignedUrl: string, fields: Record<string, string>) {
  try {
    const { id } = await Uploader.startUpload({
      filePath: filePath,
      serverUrl: presignedUrl,
      method: 'PUT',
      parameters: fields,
      notificationTitle: 'Uploading to S3'
    });

    console.log('Upload started with ID:', id);

    // Listen for upload events
    Uploader.addListener('events', (event: UploadEvent) => {
      if (event.name === 'uploading') {
        console.log(`Upload progress: ${event.payload.percent}%`);
      } else if (event.name === 'completed') {
        console.log('Upload completed successfully');
      } else if (event.name === 'failed') {
        console.error('Upload failed:', event.payload.error);
      }
    });

  } catch (error) {
    console.error('Failed to start upload:', error);
  }
}

```

### 上传到自定义服务器的示例

```typescript
import { Uploader } from '@capgo/capacitor-uploader';

async function uploadToCustomServer(filePath: string, serverUrl: string) {
  try {
    // Start the upload
    const { id } = await Uploader.startUpload({
      filePath: filePath,
      serverUrl: serverUrl,
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-auth-token-here'
      },
      parameters: {
        'user_id': '12345',
        'file_type': 'image'
      },
      notificationTitle: 'Uploading to Custom Server',
      maxRetries: 3
    });

    console.log('Upload started with ID:', id);

    // Listen for upload events
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });

    // Optional: Remove the upload if needed
    // await Uploader.removeUpload({ id: id });

  } catch (error) {
    console.error('Failed to start upload:', error);
  }
}

// Usage
const filePath = 'file:///path/to/your/file.jpg';
const serverUrl = 'https://your-custom-server.com/upload';
uploadToCustomServer(filePath, serverUrl);

```

### 示例多文件多部分上传

```typescript
import { Uploader } from '@capgo/capacitor-uploader';

const { id } = await Uploader.startUpload({
  serverUrl: 'https://api.example.com/upload',
  method: 'POST',
  uploadType: 'multipart',
  files: [
    { filePath: 'file:///...photo1.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },
    { filePath: 'file:///...photo2.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },
  ],
  parameters: { albumId: '7' },
  headers: { Authorization: 'Bearer token' },
});
console.log('Upload started with ID:', id);
```

### 带有相机相机预览的示例

联合国文件 [电容相机预览](https://github.com/Cap-go/camera-preview)

```typescript
  import { CameraPreview } from '@capgo/camera-preview'
  import { Uploader } from '@capgo/capacitor-uploader';


  async function record() {
    await CameraPreview.startRecordVideo({ storeToFile: true })
    await new Promise(resolve => setTimeout(resolve, 5000))
    const fileUrl = await CameraPreview.stopRecordVideo()
    console.log(fileUrl.videoFilePath)
    await uploadVideo(fileUrl.videoFilePath)
  }

  async function uploadVideo(filePath: string) {
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });
    try {
      const result = await Uploader.startUpload({
        filePath,
        serverUrl: 'S#_PRESIGNED_URL',
        method: 'PUT',
        headers: {
          'Content-Type': 'video/mp4',
        },
        mimeType: 'video/mp4',
      });
      console.log('Video uploaded successfully:', result.id);
    } catch (error) {
      console.error('Error uploading video:', error);
      throw error;
    }
  }
```

## API 密码

-   [`startUpload(...)`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-startupload)
-   [`uploadMultipart(...)`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-uploadmultipart)
-   [`removeUpload(...)`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-removeupload)
-   [`addListener('events', ...)`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-addlistenerevents-)
-   [`acknowledgeEvent(...)`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-acknowledgeevent)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-interfaces)

用于上传带有背景支持和进度跟踪的文件的电容上传插件 .

### iOS 设置

在iOS上,原生地层使用背景 `URLSession` 带有标识符 `CapacitorUploaderBackgroundSession`。许多应用程序可以在不添加的情况下上传 `UIBackgroundModes`; 添加 `fetch` 应用程序后需要上传时继续 暂停.

App Store 连接拒绝构建声明 `UIBackgroundModes` → `processing` 无 `BGTaskSchedulerPermittedIdentifiers`。此插件没有排程 `BGTaskScheduler` 工作,所以避开 `processing` 除非其他特性需要它. 若为 `processing` 存在(例如,来自旧的设置指南),包括 `CapacitorUploaderBackgroundSession` 内 `BGTaskSchedulerPermittedIdentifiers` 在你的应用软件 `Info.plist`。 。 。 .

### 启动装入(...)

```typescript
startUpload(options: uploadOption) => Promise<{ id: string; }>
```

开始上传文件到服务器 .

即使应用程序关闭或背景化,上传也会在背景中继续. 听上传事件跟踪进度,完成或失败.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[uploadOption](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-uploadoption)` | \- 上传配置 |

**回返情况:** `Promise<{ id: string; }>`

**自:** 0.0.1 资源

* * *

### 上传多部分(...)

```typescript
uploadMultipart(options: UploadMultipartOptions) => Promise<{ id: string; }>
```

开始上传单个文件为多段/窗体-数据.

这是一个方便的 API,用于后端,期望一个命名的文件字段和 额外的窗体字段。 现有 `startUpload` 二进制上传不变.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[UploadMultipartOptions](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-uploadmultipartoptions)` | \- 多部分上传的配置 |

**回返情况:** `Promise<{ id: string; }>`

**自:** 8.3.2 国家

* * *

### 删除上载(...)

```typescript
removeUpload(options: { id: string; }) => Promise<void>
```

取消并删除正在进行的上传 .

这将停止上传,如果它正在进行,并清理资源.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ id: string; }` | \- 包含要删除的上传ID的对象 |

**自:** 0.0.1 资源

* * *

### 添加倾听者( 事件,...)

```typescript
addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void) => Promise<PluginListenerHandle>
```

听上传进度和状态事件.

活动为:

-   上传进度更新( 含百分比)
-   上传完成( 有状态代码)
-   上传失败( 有错误和状态代码)

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'events'` | \- 一定是"活动" |
| **`listenerFunc`** | `(state: [UploadEvent](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-uploadevent)) => void` | \- 处理上传事件的回调功能 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-pluginlistenerhandle)>`

**自:** 0.0.1 资源

* * *

### 确认Event(...)

```typescript
acknowledgeEvent(options: { eventId: string; }) => Promise<void>
```

确认收到上传事件, 从插件缓存中删除 .

已完成和失败的事件被存储在插件的持久缓存中, 以便它们成为 如果应用程序在事件处理前关闭或背景化,则重新交付. 在成功处理“ 完成的” 或“ 失败的” 事件后调用此方法以预防 它从下次插件时重播开始.

进步( “ 上载 ” ) 事件没有事件标识, 不需要承认 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ eventId: string; }` | \- 包含事件的对象,需要确认 |

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

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 .

**回返情况:** `Promise<{ version: string; }>`

**自:** 0.0.1 资源

* * *

### 接口

#### 上传选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`filePath`** | `string` | 要上传的文件的本地文件路径 。 可以是文件://URL或绝对路径. 如果您需要在一个多段请求中上传多个文件, 请使用 `files`。 。 。 . |  | 0.0.1 资源 |
| **`files`** | `UploadFileOption[]` | 在单个请求中上传多个文件 。 提供后,上传为 `multipart/form-data` 每个文件有一个部分。 使用 `fieldName` 以控制每个部分的名称(例如). `images[]`) (中文(简体) ). 说明: `PUT` 上传(如被预先签名的S3 URL)只支持一个文件. |  | 0.0.3 经常预算: |
| **`serverUrl`** | `string` | 上传文件的服务器 URL 端点 . |  | 0.0.1 资源 |
| **`notificationTitle`** | `string` | 向用户显示的上传通知的标题 。 仅限Android. | `'Uploading'` | 0.0.1 资源 |
| **`headers`** | `{ [key: string]: string; }` | HTTP 头随上传请求一起发送. 可用于认证符,内容类型等. |  | 0.0.1 资源 |
| **`method`** | `'PUT' | 'POST'` | 用于上传请求的 HTTP 方法 . | `'POST'` | 0.0.1 资源 |
| **`mimeType`** | `string` | 正在上传的文件的 MIME 类型 。 如果没有指定,插件将尝试自动确定 . |  | 0.0.1 资源 |
| **`parameters`** | `{ [key: string]: string; }` | 附加表单参数随上传请求一起发送. 这些将作为形式数据列入多段上传. |  | 0.0.1 资源 |
| **`maxRetries`** | `number` | 如果上传失败, 重试的最大次数 . | `0` | 0.0.1 资源 |
| **`uploadType`** | `'binary' | 'multipart'` | 要执行的上传类型 。 - “ 二进制”:将文件上传为请求正文中的原始二进制数据 - “多部分” : 上传文件为多部分/ 窗体数据 | `` 'binary' when `method` is `'PUT'`, otherwise `'multipart'` `` | 0.0.2 (中文(简体) ) |
| **`fileField`** | `string` | 使用多段上传类型时的文件窗体字段名。 仅在上传Type为"多部分"时使用. 多文件上传 `files`,在文件条目未指定时,此字段名称被用作默认字段名称 `fieldName`。 。 。 . | `'file'` | 0.0.2 (中文(简体) ) |

#### 上传文件选项

上传文件的配置选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`filePath`** | `string` | 要上传的文件的本地文件路径 。 可以是文件://URL或绝对路径. | 0.0.3 经常预算: |
| **`fieldName`** | `string` | 使用多段上传时的文件部分的窗体字段名称 。 如果省略,则, [`uploadOption.fileField`](https://npmcn.com/package/%40capgo/capacitor-uploader/#readme-uploadoption) 被使用(默认为 `'file'`) (中文(简体) ). | 0.0.3 经常预算: |
| **`mimeType`** | `string` | 此文件的 MIME 类型 。 如果没有指定,插件将尝试自动确定 . | 0.0.3 经常预算: |

#### 上传多部分选项

启动单文件多段上传的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`url`** | `string` | 发送多段请求的服务器 URL 端点 . | 8.3.2 国家 |
| **`filePath`** | `string` | 要上传的文件的本地文件路径 。 可以是文件://URL或绝对路径. | 8.3.2 国家 |
| **`fieldName`** | `string` | 上传文件部分的窗体字段名称 . | 8.3.2 国家 |
| **`fields`** | `{ [key: string]: string; }` | 多段请求中要包含的额外窗体字段 . | 8.3.2 国家 |
| **`headers`** | `{ [key: string]: string; }` | HTTP 头随上传请求一起发送. | 8.3.2 国家 |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 上传事件

上传生命周期中排放出的事件 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`name`** | `'uploading' | 'completed' | 'failed'` | 上传状态 。 - “上载”:上传中 - “完成” : 上传成功 - “ 失败 ” : 上传遇到错误 | 0.0.1 资源 |
| **`payload`** | `{ percent?: number; error?: string; statusCode?: number; }` | 关于上传事件的附加数据. | 0.0.1 资源 |
| **`id`** | `string` | 此上传任务的独特标识符 . | 0.0.1 资源 |
| **`eventId`** | `string` | 此特定事件实例的独特标识符 。 只出现在"完成"和"失败"的事件上. 用于确认收到并删除插件缓存中的事件 。 进步("上载")事件没有事件Id,并且没有持续. | 0.0.2 (中文(简体) ) |

### 功劳:

Ios上的灵感和代码: [https://github.com/Vydia/ react-native-background-upload/tree/master 页面存档备份,存于互联网档案馆](https://github.com/Vydia/react-native-background-upload/tree/master) API定义: [https://www.npmjs.com/package/cordova-plugin-background-upload-put-s3 互联网档案馆的存檔,存档日期2014-12-21](https://www.npmjs.com/package/cordova-plugin-background-upload-put-s3)

## 常见问题

### @capgo/capacitor-uploader 是什么？

本地上传文件

### 如何安装 @capgo/capacitor-uploader？

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

### @capgo/capacitor-uploader 支持 TypeScript 吗？

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

### @capgo/capacitor-uploader 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-uploader 可以商用吗？

@capgo/capacitor-uploader 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-uploader 的下载量有多少？

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

### @capgo/capacitor-uploader 还在维护吗？

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