# @bubblewrap/cli 中文文档

规范地址：https://npmcn.com/package/%40bubblewrap/cli/

版本：1\.27\.0
npm 元数据更新时间：2026-10-09T16:11:18.812Z
中文译文更新时间：2026-11-08T17:56:24.287Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bubblewrap/cli
原文对照：https://npmcn.com/package/%40bubblewrap/cli/?lang=original
项目主页：https://github.com/GoogleChromeLabs/bubblewrap#readme
源码仓库：https://github.com/GoogleChromeLabs/bubblewrap

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

- 包体积（解压后）：189 kB，50 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：17 个
- 首次发布：2020-03-11T13:20:42.838Z
- 最新版本发布：2026-10-09T16:11:18.131Z
- 近 30 天下载量：71186（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：76（近 12 个月 3 个）

## 中文简介

从网络宣言生成 TWA 项目的 CLI 工具

## 安装

```sh
npm install @bubblewrap/cli
```

也可以使用：`pnpm add @bubblewrap/cli`、`yarn add @bubblewrap/cli`、`bun add @bubblewrap/cli`

## README

# 泡泡包装 CLI

![Node CI Status](https://github.com/GoogleChromeLabs/bubblewrap/workflows/Node%20CI/badge.svg)

Bubblewrap 是帮助开发者创建的命令行界面( CLI) a Android应用项目,使用 [受托网络活动(TWA)](https://developer.chrome.com/docs/android/trusted-web-activity/)。 。 。 .

## 所需资源

-   [节点.js](https://nodejs.org/en/) 18.0.0或以上(含)

## 建立环境

当首次运行 Bubblewrap 时, 它会自动下载和安装 外部依赖性。 这是推荐的设置,但有可能 [手动设置环境](https://npmcn.com/package/%40bubblewrap/cli/#readme-manually-setting-up-the-environment)。 。 。 .

## 集装箱

作为直接用节点(Node.js)运行您机器上的cli的替代方案,您可以使用此功能 预装了 Cli 和所有依赖性 。 使用 CL 运行 `docker run --rm -ti ghcr.io/googlechromelabs/bubblewrap:latest [cmd]` 就像你平常一样 使用情况 `bubblewrap [cmd]`。 。 。 .

## 快速启动指南

### 安装泡泡包装

```bash
npm i -g @bubblewrap/cli
```

: 警告: **警告:** 别用 `sudo npm i -g @bubblewrap/cli` 安装泡泡包装。 使用 `npm` 命令为 `sudo` 应避免造成不同种类的问题(见e/cn.4/sub.2/2000/l.48) [这里](https://medium.com/@ExplosionPills/dont-use-sudo-with-npm-still-66e609f5f92) 财务报告和审定财务报表 [这里](https://medium.com/@ExplosionPills/dont-use-sudo-with-npm-5711d2726aa3)) (中文(简体) ).

### 启动一个 Android 项目

从已有的 Web 声明生成一个 Android 项目:

```bash
bubblewrap init --manifest https://my-twa.com/manifest.json
```

当启动项目时, Bubblewrap 将下载《网络宣言》, 请您确认 用于构建Android工程的数值.

它还会要求您提供生成签名密钥所需的细节,用于签名 在上传到 Play Store 之前应用 .

> :grey exclaim:尽管我们推荐了 Bubblewrap 用于建造和生成一个签名 APK, 来自 `init` 命令是一个正常的Android工程,可以打开 并使用 [Android 工作室](https://developer.android.com/studio/)请参考 [文档](https://developer.android.com/studio/publish/app-signing#sign-apk) 用于构建和签名 使用Android Studio的应用程序.

### 建造Android项目

```bash
bubblewrap build
```

在首次构建项目时,需要安装Android Build Tools. 该工具将引用构建工具的安装过程. 确保阅读和接受 许可协议在程序前。 此进程将在 `directory/decompressed` android CLI 软件包的根目录.

由于建设步骤,该工具将生成一个签名APK(`app-release-signed.apk`(中文(简体) ) 用于测试应用程序和已签名的 AppBundle(`./app-release-bundle.aab`这可以是 [上传到游戏存储器](https://android-developers.googleblog.com/2020/08/recent-android-app-bundle-improvements.html)。您还需要向 验证您的域 。 这个 [TWA 快速启动指南](https://developers.google.com/web/updates/2019/08/twas-quickstart#creating-your-asset-link-file) 解释如何提取生成信息所需的信息.

## 图标

![Overview of bubblewrap commands](https://npmcn.com/package/%40bubblewrap/cli/command_flow.svg)

上图显示(在黑框中)哪些命令作为输入或输出各种文件(以白色椭圆)而产生. 指向文件的箭头指"创建或修改",指向命令的箭头指"被用做输入".

## `init`

用法 :

从网络宣言中初始化一个信任的网络活动Android项目. 输入脚本 分析 Web 显示并生成Android 项目的默认值。 这个 将提示用户确认或输入无法生成的值.

```
bubblewrap init --manifest="<web-manifest-url>" [--directory="<path-to-output-location>"] [--chromeosonly] [--metaquest]
```

选项 :

-   `--directory`: 生成工程的路径。 当前目录的默认值 .
-   `--chromeosonly`:此旗下指定了只用于Chrome OS的构建,并阻止非Chrome OS设备安装应用.
-   `--metaquest`: 此旗帜指定构建将兼容Meta Quest设备.
-   `--alphaDependencies`: 启用依赖于即将到来的Android 库版本的特性 用于信任的网络活动或仍然不稳定的网络活动.

## `build`

将项目构建为最终的APK,可以上传到Play Store.

命令会向用户询问它们存储密钥密码. 或者,用户可以设置 密码为 environtic 变量, 允许运行 `build` 作为持续整合的一部分. 设定 `BUBBLEWRAP_KEYSTORE_PASSWORD` 密钥存储密码和 `BUBBLEWRAP_KEY_PASSWORD` 作为密钥密码.

用法 :

```
bubblewrap build [--skipPwaValidation] [--skipSigning] [--manifest="<path-twa-manifest>"] [--signingKeyPath="<path-to-signing-key>"] [--signingKeyAlias="<key-alias>"]
```

选项 :

-   `--skipPwaValidation`:跳过将包裹的PWA与质量标准进行验证.
-   `--skipSigning`:跳过已建APK和App Bundle的签名. 其他与签名相关的旗帜在使用时会被忽略.
-   `--signingKeyPath`: 用于签名已建APK和App Bundle的密钥托尔路径 。 覆盖签名 Key. path 指定于 `twa-manifest.json`。 。 。 .
-   `--signingKeyAlias`: 键名. 签名 `twa-manifest.json`。 。 。 .
-   `--manifest`: 客户端应当查找的目录 `twa-manifest.json`。 。 。 .

## `update`

重生成 Android 项目文件 `twa-manifest.json` 文档.

: 警告: **警告:** Bubblewrap不期望生成的Android项目会使用 外出编辑. 手动添加到Android项目的任何文件将被删除或覆盖 何时 `update` 执行。 变动至 `twa-manifest.json` 被保留下来.

用法 :

```
bubblewrap update [--appVersionName="<version-string>"] [--skipVersionUpgrade] [--manifest="<path-twa-manifest>"]
```

选项 :

-   `--appVersionName`: 升级时使用版本名. 如果 `--skipVersionUpgrade` 已使用.
-   `--skipVersionUpgrade`: 跳过升级 `appVersion` 财务报告和审定财务报表 `appVersionCode`。 。 。 .
-   `--manifest`: 客户端应当查找的目录 `twa-manifest.json`。 。 。 .

## `validate`

验证PWA再次验证在信任的网络活动中使用的质量标准.

用法 :

```
bubblewrap validate --url=[pwa-url]
```

## `install`

将输出命令中生成的应用程序安装到连接用于调试的设备上 .

用法 :

```
bubblewrap install [--apkFile="/path-to-apk/apkfile.apk"]
```

选项 :

-   `--apkFile`:要安装的APK文件路径. 默认为 `./app-release-signed.apk`。 。 。 .
-   `--verbose`:打印正在执行的adb命令.

## `help`

显示命令和选项列表.

用法 :

```
bubblewrap help
```

## `doctor`

验证 jdk 和 AndroidSdk 位于您配置指定的路径 他们必定是遵循正道的.

用法 :

```
bubblewrap doctor
```

## `updateConfig`

设置 jdk 或 AndroidSdk 到给定路径的路径 .

用法 :

```
bubblewrap updateConfig  --jdkPath="/path-to-jdk" --androidSdkPath="/path-to-androidSdk"
```

选项 :

-   `--jdkPath`:设置jdk路径到给定路径.
-   `--androidSdkPath`:设置AndroidSdk给定的路径.

## `merge`

将用户的网络显示合并到他们的twaManifest.json.

用法 :

```
bubblewrap merge --ignore [fields-list]
```

选项 :

-   `--appVersionName`: 升级时使用版本名. 如果 `--skipVersionUpgrade` 已使用.
-   `--skipVersionUpgrade`: 跳过升级 `appVersion` 财务报告和审定财务报表 `appVersionCode`。 。 。 .
-   `--ignore`:忽略列表中的所有字段。 接受所有可能字段 在《网络宣言》中.

## `fingerprint`

管理用于生成用于网络应用程序的数字资产链接文件的指纹列表.

用法 :

```bash
bubblewrap fingerprint [subcommand]
```

全球旗帜 :

-   `--manifest=<manifest>`: 信任的网络活动配置路径 。',

### 子命令 :

#### `add`

在工程配置中添加指纹.

用法 :

```
bubblewrap fingerprint add [SHA-256 fingerprint] <flags>
```

其它旗帜 :

-   `--name=<name>`:可选设置名来帮助识别指纹. 名字已经打印 与指纹一起使用 `list` 子命令 .

#### `remove`

从工程配置中删除指纹.

用法 :

```
bubblewrap fingerprint remove [SHA-256 fingerprint] <flags>
```

#### `list`

列出项目配置中的指纹.

用法 :

```
bubblewrap fingerprint list <flags>
```

#### `generateAssetLinks`

从工程配置生成一个资产链接文件

用法 :

```
bubblewrap fingerprint generateAssetLinks <flags>
```

旗帜 :

-   `--output=<filename>`: 从何处装入工程配置的路径.

## `play`

管理您的 Google 游戏项目的文物 .

用法 :

```bash
bubblewrap play [subcommand]
```

**说明**数字 : 这些功能需要有一个服务账户文件才能正确工作. 请看 [此文档](https://github.com/chromeos/pwa-play-billing#setup-a-service-account) 设立服务账户.

全局旗 (可以适用于所有特性命令):

-   `--serviceAccountFile`: 将服务账户json文件位置设置在 twa - manifest 中 .
-   `--manifest`: 指定当前目录中未使用的显示文件.

### 子命令

#### `publish`

向 Play Store 提供捆绑的发布 .

用法 :

```bash
bubblewrap play publish --serviceAccountFile="/path/to/service/account.json" --track="beta" --appBundleLocation="/home/appBundle.aab"
```

选项 :

-   `--track`: 将预建文件发布到 Google Play Store 指定音轨(默认为内部音轨).
-   `--appBundleLocation`:指定上传到Google Play的应用程序位置(默认为当前目录).

#### `retain`

:警告:这是一个实验性特征.

用法 :

```bash
bubblewrap play retain --add=86
```

选项 :

-   `--add`:指定要保存的捆绑以放出(如果只放出一款Chrome OS,这只能是Android捆绑).
-   `--remove`: 如果不再相关, 删除指定的捆绑 .
-   `--list`:在 twa-manifest.json 中显示已保留捆绑的列表,而非从游戏中保留的内容.

#### `versionCheck`

用法 :

```bash
bubblewrap play versionCheck --serviceAccountFile="/path/to/service/account.json"  --targetDirectory="/home/my/app/dir"
```

选项 :

-   `--targetDirectory`: 版本检查应运行的目录(默认为当前目录)。 这应该是你的气泡包工程目录.

## `twa-manifest.json` 参考文献

这个 `twa-manifest.json` 文件以 `init` 已昏迷并包含配置 安卓应用.

运行后想要更改应用程序配置的开发者 `init` 可以通过 编辑此文件然后运行 `update` 命令.

字段 :

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 额外信任的奥里金斯 | 字符串 \[\] | 虚假 | 由开发商拥有并被"数字资产链接"验证的额外起源列表. 用户在浏览应用程序内部的出处时会保持全屏模式. |
| 字母 | [阿尔法依赖](https://npmcn.com/package/%40bubblewrap/cli/#readme-AlphaDependencies) | 虚假 | 允许Android应用程序使用依赖性的α版本. 默认为 `false`。 。 。 . |
| 应用程序 | 字符串 | 虚假 | `versionName` android应用软件。 检查 [Android 文档](https://developer.android.com/studio/publish/versioning) 详细情况. |
| 应用程序代码 | 编号 | 虚假 | `versionCode` android应用软件。 检查 [Android 文档](https://developer.android.com/studio/publish/versioning) 详细情况. |
| 背景颜色 | 字符串 | 真实 | 喷出屏幕背景所用的颜色 . |
| 显示 | `'standalone'` | `'fullscreen'` | `'fullscreen-sticky'` | 虚假 | 初始数据 [显示模式](https://developer.mozilla.org/en-US/docs/Web/Manifest/display) android应用软件. `fullscreen-sticky` 对应于Android的: [隐形粘贴](https://developer.android.com/training/system-ui/immersive#sticky-immersive)默认为 `standalone`。 。 。 . |
| 启用通知 | 布尔 | 真实 | 设定为 `true` 允许通知代表团. |
| 启用SiteSettingsShortcut | 布尔 | 虚假 | 向应用程序启动器中的站点设置添加快捷键。 默认为 `true`。 。 。 . |
| 倒置类型 | `'customtabs'` | `'webview'` | 虚假 | 当用户设备上没有支持信任的Web活动的浏览器时使用的倒置策略. 默认为 `'customtabs'`。 。 。 . |
| 特性 | [特征](https://npmcn.com/package/%40bubblewrap/cli/#readme-Features) | 虚假 | 启用Android应用程序中的可选特性。 读取 [特征](https://npmcn.com/package/%40bubblewrap/cli/#readme-Features) 详细情况. |
| 指纹 | [指纹](https://npmcn.com/package/%40bubblewrap/cli/#readme-fingerprint)\[ | 虚假 | 用于生成"数字资产链接"文件的指纹列表. 读取 [指纹](https://npmcn.com/package/%40bubblewrap/cli/#readme-fingerprint) 详细情况. |
| 生成器App | 字符串 | 虚假 | 用于生成Android项目的工具的标识符 。 泡泡包装的使用 `bubblewrap-cli`。只能由生成程序修改. |
| 东道主 | 字符串 | 真实 | 将在信任的网络活动中打开的源 . |
| 图标Url | 字符串 | 真实 | 应用程序启动器和喷出屏幕所用的图标的完整 URL 。 必须是至少512x512px. |
| 是 ChromeOS 仅此而已 | 布尔 | 虚假 | 生成只针对ChromeOS设备的应用程序. 默认为 `false`。 。 。 . |
| 是 Meta 查询 | 布尔 | 虚假 | 生成一个兼容Meta Quest设备的应用程序. 默认为 `false`。 。 。 . |
| 发射器Name | 字符串 | 虚假 | 在Android发射器上显示的Android应用程序的简称 |
| 可掩码IconUrl | 字符串 | 虚假 | 当设备支持时,可遮掩图标所用的图标的完整 URL . |
| 单色IconUrl | 字符串 | 虚假 | 完整 URL 到单色图标, 当显示通知时使用 . |
| 名称 | 字符串 | 真实 | Android应用程序的名称,安装在Android设备时显示在平地上. |
| 导航颜色 | 字符串 | 真实 | 导航栏所用的颜色 . |
| 导航颜色 | 字符串 | 虚假 | 设备处于暗模式时用于导航栏的颜色. 默认为 `#000000`。 。 。 . |
| 导航 分块颜色 | 字符串 | 虚假 | 导航条分隔符所用的颜色 。 默认为 `#000000`。 。 。 . |
| 导航 Divider 颜色 | 字符串 | 虚假 | 当设备为暗模式时用于导航条分隔器的颜色. 默认为 `#000000`。 。 。 . |
| 方向 | `'default'` | `'any'` | `'natural'` | `'landscape'` | `'portrait'` | `'portrait-primary'` | `'portrait-secondary'` | `'landscape-primary'` | `'landscape-secondary'` | 虚假 | 初始方向用于启动Android应用. 默认为 `'default'`。 。 。 . |
| 软件包编号 | 字符串 | 真实 | 这个 [应用程序编号](https://developer.android.com/studio/build/application-id) 用于输出Android应用程序. |
| 保留 套装 | 阵列 | 虚假 | 这些是您在发布新捆绑时想要保留的应用程序捆绑的捆绑. |
| 服务账户JsonFile | 字符串 | 虚假 | Play Store服务了账户信息. [设立指南](https://github.com/chromeos/pwa-play-billing#setup-a-service-account) |
| 共享目标 | [共享目标](https://w3c.github.io/web-share-target/#sharetarget-and-its-members) | 虚假 | [网络共享目标](https://web.dev/web-share-target/) 应用程序的配置 . |
| 快捷键 | [快捷键信息](https://developer.mozilla.org/en-US/docs/Web/Manifest/shortcuts)\[ | 虚假 | [快捷键](https://web.dev/app-shortcuts/) 应用程序的配置 . |
| 签名键 | [签名KeyInfo](https://npmcn.com/package/%40bubblewrap/cli/#readme-SigningKeyInfo) | 真实 | 用于签名Android应用程序的签名密钥和别名. 读取 [签名KeyInfo](https://npmcn.com/package/%40bubblewrap/cli/#readme-SigningKeyInfo) 详细情况. |
| 飞出时间 | 编号 | 真实 | 喷出屏幕的持续时间淡出动画 . |
| 启动Url | 字符串 | 真实 | TWA的起步路径. 必须是相对于域. |
| 主题颜色 | 字符串 | 真实 | 状态栏所用的颜色 . |
| 主题颜色 | 字符串 | 真实 | 暗状态栏所用的颜色 . |
| 网络管理 | 字符串 | 虚假 | PWA网络宣言的完整URL. 要求应用程序与Chrome OS和Meta Quest设备兼容. |
| 全部扩展Url | 字符串 | 虚假 | 浏览器认为在应用程序内的导航范围. 如果用户在范围外导航,则返回浏览器标签或窗口内的普通网页. 必须是完整的 URL 。 仅由 Meta Quest 设备要求和使用 . |
| 薄荷丝克Version | 编号 | 虚假 | 最低限度 [Android API 级别](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) 用于应用程序运行。 默认为 `23`,如果 `isMetaQuest` 实值 `true`,以及 `19` 否则. |
| 操作程序 | [礼宾管理员](https://npmcn.com/package/%40bubblewrap/cli/#readme-protocolhandlers)\[ | 虚假 | 清单 [协议处理器](https://npmcn.com/package/%40bubblewrap/cli/#readme-protocolhandlers) 由应用程序支持. |
| 文件处理器 | [文件处理器](https://npmcn.com/package/%40bubblewrap/cli/#readme-fileHandlers)\[ | 虚假 | 清单 [文件汉德尔斯](https://npmcn.com/package/%40bubblewrap/cli/#readme-fileHandlers) 由应用程序支持. |
| 启动手提电脑模式 | 字符串 | 虚假 | 启动( h) [客户端 模式](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/launch_handler#client_mode) 该应用程序. |

### 特征

开发者可以在他们的Android应用中启用额外的功能. 一些特性可能包括应用程序中更多的依赖性并增加二进制大小.

| 名称 | 类型 | 需求 | 增加二进制大小 | 说明 |
| :-: | :-: | :-: | :-: | :-: |
| 应用程序飞行器 | [应用飞行器配置](https://npmcn.com/package/%40bubblewrap/cli/#readme-appsflyerconfig) | 虚假 | 真实 | 读取 [应用飞行器配置](https://npmcn.com/package/%40bubblewrap/cli/#readme-appsflyerconfig) 详细情况. |
| 第一个运行旗 | [第一跑道旗舰](https://npmcn.com/package/%40bubblewrap/cli/#readme-firstrunflagconfig) | 虚假 | 虚假 | 读取 [第一跑道旗舰](https://npmcn.com/package/%40bubblewrap/cli/#readme-firstrunflagconfig) 详细情况. |
| 代表团 | [代表团配置](https://npmcn.com/package/%40bubblewrap/cli/#readme-locationdelegationconfig) | 虚假 | 真实 | 读取 [代表团配置](https://npmcn.com/package/%40bubblewrap/cli/#readme-locationdelegationconfig) 详细情况. |
| 播放比灵 | [播放比尔林配置](https://npmcn.com/package/%40bubblewrap/cli/#readme-playbillingconfig) | 虚假 | 真实 | 读取 [播放比尔林配置](https://npmcn.com/package/%40bubblewrap/cli/#readme-playbillingconfig) 详细情况. |

#### 应用飞行器配置

启用 [应用飞行器 SDK](https://support.appsflyer.com/hc/en-us/articles/360002330178-Using-AppsFlyer-with-TWA#introduction) 在Android应用程序中。 包括额外的库并不符合Chrome OS.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 应用程序飞行器 | 布尔 | 真实 | 应用飞行器识别码. |
| 启用 | 布尔 | 真实 | 设定为 `true` 以启用特性. |

#### 代表团配置

向Android系统代表位置权限对话框,而不是显示浏览器对话框. 当应用程序请求定位许可时被推荐,但默认无法启用,因为它包含了应用程序中的额外依赖性.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 启用 | 布尔 | 真实 | 设定为 `true` 以启用特性. |

#### 播放比尔林配置

启用应用程序中的 Play Billing 集成并允许网络应用程序到 [使用数字货物 API 接收付款](https://developer.chrome.com/docs/android/trusted-web-activity/receive-payments-play-billing/)。包括Android应用中的额外依赖性.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 启用 | 布尔 | 真实 | 设定为 `true` 以启用特性. |

#### 第一跑道旗舰

启动应用程序时添加额外的查询参数,显示应用程序是否首次运行.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 启用 | 布尔 | 真实 | 设定为 `true` 以启用特性. |
| 查询参数Name | 字符串 | 真实 | 用于将首个运行信息附加到 `start-url`。 。 。 . |

### 阿尔法依赖

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 启用 | 布尔 | 虚假 | 设定为 `true` 允许应用程序使用 alpha 版本 [`android-browser-helper`](https://github.com/GoogleChrome/android-browser-helper)。 。 。 . |

### 签名KeyInfo

关于文件系统位置和用于签名Android应用程序的别名的信息.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 路径 | 字符串 | 真实 | 本地文件系统中的密钥文件路径 |
| 别名 | 字符串 | 真实 | 用于在密钥托里签名的密钥的别名 |

### 指纹

申请的签名指纹信息. 用于生成 `assetlinks.json` 文件,并由 `fingerprint` 命令.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 名称 | 字符串 | 虚假 | 指纹的可选名称. |
| 价值 | 字符串 | 真实 | 指纹的SHA-256值. |

### 礼宾管理员

为申请注册的礼宾处理员名单. 这些条目可能并不完全符合网页上最初的内容,因为这些条目已经正常化并经过验证 [这些](https://wicg.github.io/manifest-incubations/#processing-the-protocol_handlers-member) 规则。 如果一个webmanifest条目出于任何原因(无效协议,错误的目标url,丢失"%s"令牌)是不正确的,将会被忽略并打印出警告. 见 [这里](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/protocol_handlers) 欲了解更多关于《议定书》处理器规格的信息。 支持协议的完整列表是 [这里](https://github.com/GoogleChromeLabs/bubblewrap/blob/main/packages/core/src/lib/types/ProtocolHandler.ts)。 。 。 .

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 协议 | 字符串 | 真实 | 登记的数据方案(例如:. `bitcoin`, (中文(简体) ), `irc`, (中文(简体) ), `web+coffee`) (中文(简体) ). |
| url 密码 | 字符串 | 真实 | 将自定义数据方案转换回 http(s) 链接的公式,必须包含“%s” , 并且与 Web 显示文件来源相同 。 示例 `https://test.com/?target=%s` |

### 文件处理器

为应用程序注册的文件处理器列表 。 这些条目可能并不完全符合网页上的最初内容。 如果一个webmanifest条目因任何原因不正确,将会被忽略并打印出警告. 见 [这里](https://developer.chrome.com/docs/capabilities/web-apis/file-handling?hl=en) 关于文件处理的更多信息 [这里](https://wicg.github.io/manifest-incubations/#file_handlers-member) 用于文件 handlers webmanifest spec.

| 名称 | 类型 | 需求 | 说明 |
| :-: | :-: | :-: | :-: |
| 动作Url | 字符串 | 真实 | 如果文件处理器发射时匹配相应的 MIME 类型, 要导航的 URL |
| mIME 类型 | 字符串 \[\] | 真实 | 文件处理器的 MIME 类型列表 |

### 发射手

字符串,指定应用程序在启动时要加载的上下文 。 可能的值有:"自动","焦点-存在","navigate-存在","navigate-new"等. 见 [启动( h)](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/launch_handler) 更多信息.

## 手动建立环境

### 获得Java开发工具包(JDK) 17.

Android命令行工具需要JDK的正确版本来运行. 防止版本 与已经安装的 JDK 版本相冲突, Bubblewrap 使用可以解析的 JDK 一个单独的文件夹.

下载与您的操作系统兼容的 JDK 17 版本 [收养](https://adoptium.net/temurin/releases/?version=17&package=jdk) 在自己的文件夹中提取它.

: 警告: **警告:** 使用低于17的版本将无法编译项目和更高 版本与Android命令行工具不相容.

### 获取 Android 命令行工具

下载与您的操作系统兼容的Android命令行工具 [https://developer.android.com/studio#命令-行-工具-只限](https://developer.android.com/studio#command-line-tools-only)。 。 。 . 创建文件夹并提取下载的文件到其中 。 这将进一步安装AndroidSdk和Android SDK管理器而无需安装整个Android IDE.

### 告诉 Bubblewrap JDK 和 Android 命令行工具在哪里

运行时 `bubblewrap` 它将首次询问它在哪里能找到 JDK 和 Android 命令 线上工具。 所以,注意双方被解压的地点.

为确保您注意到正确的位置, 请检查每个目录是否包含以下文件 :

-   打开 **窗口** 财务报告和审定财务报表 **链接**,对 **打开 JDK** 路径应当包含 `bin`, (中文(简体) ), `include` , (中文(简体) ),`lib`等 (中文(简体) ). 打开 **麦克OS**, (中文(简体) ), 目录应包含 `Contents` 子目录.
-   这个 **AndroidSDK 软件** 路径应当包含 `tools` 应该有 `bin`, (中文(简体) ), `cli`

### 更新 JDK 和 / 或 Android 命令行工具的位置 .

如果 JDK 或 Android 命令行工具的位置设置错误路径或 如果它们的位置在初始配置后有所改变,则其中任何一个的位置都可以 通过编辑配置文件来更改 `${USER_HOME}/.bubblewrap/config.json`。 。 。 .

#### 样本配置.json

```
{
  "jdkPath":"\\user\\home\\bubblewrap-user\\open-jdk",
  "androidSdkPath":"\\user\\home\\bubblewrap-user\\android-cli"
 }

```

_(注:确保你没有 `spaces` 在机器人SdkPath。 检查 [此链接](https://stackoverflow.com/questions/37052934/android-sdk-location-should-not-contain-whitespace-as-this-cause-problems-with) 详细情况。 )_

## 捐款

见 [捐款](https://npmcn.com/package/CONTRIBUTING.md) 为了更多.

## 许可证

见 [自由主义](https://npmcn.com/package/LICENSE) 为了更多.

## 免责声明

这不是谷歌的产品.

## 常见问题

### @bubblewrap/cli 是什么？

从网络宣言生成 TWA 项目的 CLI 工具

### 如何安装 @bubblewrap/cli？

在项目目录运行 npm install @bubblewrap/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bubblewrap，可以用 npx bubblewrap 直接运行。

### @bubblewrap/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bubblewrap\_\_cli 是否存在。

### @bubblewrap/cli 需要什么版本的 Node\.js？

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

### @bubblewrap/cli 可以商用吗？

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

### @bubblewrap/cli 的下载量有多少？

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

### @bubblewrap/cli 还在维护吗？

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