# @capgo/capacitor-file-compressor 中文文档

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

版本：8\.1\.19
npm 元数据更新时间：2026-11-09T07:00:09.289Z
中文译文更新时间：2026-11-09T03:20:53.903Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：129 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-19T01:42:16.067Z
- 最新版本发布：2026-11-09T07:00:08.839Z
- 近 30 天下载量：52957（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

IOS、Android和Web平台上高效支持PNG、JPEG和WebP格式的图像压缩电容插件

## 安装

```sh
npm install @capgo/capacitor-file-compressor
```

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

## README

# @ capgo/ 容器- 文件- 压缩器

在上传前在设备上压缩并调整图像大小,并在JPEG,PNG和WebP之间转换. 更小的文件意味着更快地上传并降低存储成本.

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

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

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

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

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

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

## 主要特点

-   **一通电话**数字 : `compressImage()` 以宽度、高度和质量来调整和压缩大小.
-   **格式转换**:在Android和网络上输出JPEG,PNG或WebP. iOS增加了HEIF或HEIC,而WebP需要iOS 14或后期.
-   **智能尺寸**: 保持宽度比并永不提升.
-   **最佳尺寸**:如果结果大于来源,则损失格式的质量会降低。 PNG没有质量设置,因此输出仍然可以更大.
-   **隐私**: EXIF元数据在压缩时被删除.
-   **平台**:iOS,Android和Web. iOS使用图像IO,Android使用 `Bitmap`,网络使用画布.

## 为什么是文件压缩机?

用于 **客户端图像压缩**数字 :

-   **格式转换** - 将HEIF、PNG、WebP、GIF以及更多的数据转换为JPEG、PNG、WebP或HEIF
-   **多种格式** - 以平台特定产出格式提供广泛的投入支持
-   **质量控制** - 可调整压缩质量(0.0-1.0)
-   **智能调整大小** - 自动维护宽比而不扩大
-   **跨平台** - 一致的API跨iOS,Android,和Web
-   **无后端** - 所有压缩都发生在设备上

对于需要优化图像上传,减少存储,或改善性能而不进行服务器侧处理的应用程序来说,至关重要.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/file-compressor/ 互联网档案馆的存檔,存档日期2013-12-12](https://capgo.app/docs/plugins/file-compressor/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页: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-file-compressor` plugin in my project.
```

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

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

## 格式转换

插件接受通用图像格式作为输入,并将其转换为 `mimeType` 你请求.

| 平台 | 输入格式 | 输出格式 |
| --- | --- | --- |
| iOS系统 | JPEG、PNG、WebP、GIF、BMP、TIFF、HEIF/HEIC | JPEG、巴布亚新几内亚、HEIF/HEIC、WebP(iOS 14+) |
| 机器人 | JPEG、PNG、WebP、GIF、BMP、HEIF/HEIC(API 28+) | JPEG, 巴布亚新几内亚, WebP |
| 网页 | 浏览器可以解码的任何格式 | JPEG, 巴布亚新几内亚, WebP |

```typescript
import { FileCompressor } from '@capgo/capacitor-file-compressor';

// Convert an iPhone HEIF photo to JPEG before upload
const result = await FileCompressor.compressImage({
  path: heifFileUri,
  width: 1920,
  height: 1080,
  quality: 0.7,
  mimeType: 'image/jpeg',
});
```

注意: EXIF元数据在所有平台的压缩过程中被删除.

## API 密码

-   [`compressImage(...)`](https://npmcn.com/package/%40capgo/capacitor-file-compressor/#readme-compressimage)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-file-compressor/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-file-compressor/#readme-interfaces)

用于图像压缩的电容文件压缩器插件接口.

### 压缩图像(...)

```typescript
compressImage(options: CompressImageOptions) => Promise<CompressImageResult>
```

压缩带有指定尺寸和质量设置的图像文件.

这种方法在保持可接受质量的同时压缩图像以缩小文件大小. 它支持跨通用图像格式的再大小和格式转换.

**支持的输入格式( 平台解码器依赖性):** JPEG、PNG、WebP、GIF、BMP、TIFF、HEIF/HEIC

**支持的输出格式 :**

-   **iOS: (英语)** `image/jpeg`, (中文(简体) ), `image/png`, (中文(简体) ), `image/heif`, (中文(简体) ), `image/heic`, (中文(简体) ), `image/webp` (iOS 14+) (中文(简体) )
-   **机器人:** `image/jpeg`, (中文(简体) ), `image/png`, (中文(简体) ), `image/webp`
-   **网络 :** `image/jpeg`, (中文(简体) ), `image/png`, (中文(简体) ), `image/webp`

**重要注释 :**

-   在压缩所有平台时删除 EXIF 元数据
-   如果只提供1个维,则自动保持光谱比
-   当提供宽度和高度时,图像可以放在盒子内而无需缩放
-   压缩后的文件保存到本地平台的临时目录
-   如果被编码的输出会大于源文件,则在保持所请求的输出格式的同时会自动降低质量

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[CompressImageOptions](https://npmcn.com/package/%40capgo/capacitor-file-compressor/#readme-compressimageoptions)` | \- 图像压缩的配置选项 |

**回返情况:** `Promise<[CompressImageResult](https://npmcn.com/package/%40capgo/capacitor-file-compressor/#readme-compressimageresult)>`

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

* * *

### 获取 PluginVersion ()

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

获取本地 Capacitor 插件版本 .

返回本地插件执行版本 . 用于调试和确保兼容性 .

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

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

* * *

### 接口

#### 压缩图像

压缩一相之结果.

包含文件路径( 本地平台) 或 Blob( 网络平台) 取决于压缩在哪里进行.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 压缩图像的文件路径 . **平台:** Android,iOS只指(在Web上未定义)一个包含被压缩图像的临时文件. iOS上,一般为 `NSTemporaryDirectory()`。在Android上,一般在应用程序缓存目录中. **重要内容:** 这些文件可能由操作系统清理. 复制到长期使用所需的永久存储. | 7.0.0 (单位:千美元) |
| **`blob`** | `Blob` | 压缩图像的blob . **平台:** 只Web(在iOS/Android上未定义)包含被压缩的图像数据的A Blob对象. 可用于: - 为预览创建对象 URL : `URL.createObjectURL(blob)` - 通过FormData上传到服务器 - 保存到索引 DB 或其他存储 - 用文件阅读器转换到基数64 | 7.0.0 (单位:千美元) |

#### 压缩图像选项

压缩图像的选项.

配置压缩行为,包括质量、尺寸和输出格式. 路径(本土)和blob(网络)都有特定平台选项.

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`path`** | `string` | 图像压缩的文件路径 . **平台:** Android,iOS只接受(不支持在Web上)各种路径格式: - iOS: `file://` URL或绝对路径 - Android : `content://` 核电站, `file://` URL,或绝对路径 常见的输入格式包括:JPEG,PNG,WebP,GIF,BMP,TIFF,和HEIF/HEIC. |  | 7.0.0 (单位:千美元) |
| **`blob`** | `Blob` | 要压缩图像的文件 blob . **平台:** 仅Web(在iOS/Android上不支持) 在从文件输入中压缩图像,获取回复,或在网络应用程序中的任何其他 Blob 源时使用此功能. |  | 7.0.0 (单位:千美元) |
| **`quality`** | `number` | 压缩图像的质量. **范围 :** 0.0 到 1.0 - 0 `0.0` = 最大压缩(质量最低,文件最小) - `1.0` = 最小压缩(最高质量,最大文件) - `0.6` = 默认平衡压缩 **平台:** 所有平台 更高的质量值导致文件更大,但视觉质量更好. 实际压缩比取决于图像内容和格式. PNG输出忽略了质量,因为它是无损失的. | `0.6` | 7.0.0 (单位:千美元) |
| **`width`** | `number` | 压缩图像以像素表示的宽度. **平台:** 所有平台 如果只指定了宽度,则会自动计算出高度以保持原来的相相比. 如果同时指定了宽度和高度,图像会缩放到该框内,同时保持宽度比. 图像从未升级. |  | 7.0.0 (单位:千美元) |
| **`height`** | `number` | 压缩图像以像素为单位的高度. **平台:** 所有平台 如果只指定了高度,则会自动计算出宽度来维持原来的相相比. 如果同时指定了宽度和高度,图像会缩放到该框内,同时保持宽度比. 图像从未升级. |  | 7.0.0 (单位:千美元) |
| **`mimeType`** | `string` | 压缩输出图像的 MIME 类型 . **平台支持:** - 说吧 **iOS: (英语)** `image/jpeg`, (中文(简体) ), `image/png`, (中文(简体) ), `image/heif`, (中文(简体) ), `image/heic`, (中文(简体) ), `image/webp` (iOS 14+) - **机器人:** `image/jpeg`, (中文(简体) ), `image/png`, (中文(简体) ), `image/webp` - 说吧 **网络 :** `image/jpeg`, (中文(简体) ), `image/png`, (中文(简体) ), `image/webp` 使用此选项在压缩时将源图像转换为其它格式 . **格式特征 :** - 说吧 **JPEG : (英语)** 普遍支持,对照片好,不透明 **巴布亚新几内亚:** 无损失,支持透明度 **网络P :** 更好的压缩,支持透明度 - **赫尔夫/赫克:** IOS 上的有效图片格式 | `"image/jpeg"` | 7.0.0 (单位:千美元) |

## 常见问题

### @capgo/capacitor-file-compressor 是什么？

IOS、Android和Web平台上高效支持PNG、JPEG和WebP格式的图像压缩电容插件

### 如何安装 @capgo/capacitor-file-compressor？

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

### @capgo/capacitor-file-compressor 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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