了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

发布扩展程序

本页介绍了如何在 Extensions Hub 上发布扩展程序。

准备工作

如需发布扩展程序，您首先需要注册成为扩展程序发布商。

可验证的源代码

在 Extensions Hub 上发布的所有扩展程序都必须具有可公开验证的源代码。您不必将扩展程序的源代码直接上传至 Extensions Hub，只需指定源代码的位置，Extensions Hub 便会从该位置下载并构建源代码。

目前，这意味着您的扩展程序源代码将在一个公共 GitHub 代码库中公开提供。

上传可验证的源代码有几个好处：

用户可以检查要安装的扩展程序的特定修订版本的源代码。
您可以确保仅上传自己想要上传的内容，而不上传尚未完成的内容或是开发期间遗留下来的零散文件。

建议的开发周期

Firebase Extensions 开发工具支持上传扩展程序的预发布版本，这样您便可以在最终发布扩展程序的同一环境中测试扩展程序及扩展程序安装流程。

借助此功能，您可以实现如下开发周期：

使用 Firebase Emulator Suite 开发扩展程序并对其进行快速迭代。
通过本地源代码安装扩展程序，以在真实项目中测试扩展程序：
```
firebase ext:install /path/to/extension
firebase deploy --only extensions
```
将预发布版本上传到 Extensions Hub（详情请见下文）。分发安装链接以进行更广泛的测试，并根据需要上传更多预发布版本以进行迭代。
将最终的稳定版上传到 Extensions Hub（详情请见下文），并提交以供审核。如果扩展程序通过审核，则会在 Extensions Hub 上发布。
递增 extension.yaml 中的版本号，并对扩展程序的下一个版本重复此周期。

上传新的扩展程序

如果您是首次上传某个扩展程序，请按以下步骤操作：

可选：将代码提交到一个公共 GitHub 代码库。
运行 Firebase CLI 的 ext:dev:upload 命令：
GitHub
```
firebase ext:dev:upload your_publisher_id/your_extension_id
```
本地源代码
```
cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local
```
在命令调用中，您可以指定以下内容：
- 您注册的发布商 ID。
- 用于标识扩展程序的 ID 字符串。您可以采用以下格式为您的扩展程序命名：firebase-product-description-of-tasks-performed。例如：firestore-bigquery-export
该命令将提示您提供其他信息：
- 如果您是从 GitHub 上传：
  - GitHub 中该扩展程序的代码库的网址。请注意，一个代码库可以包含多个扩展程序，但每个扩展程序都必须有自己专用的根目录。
    
    首次上传一个新的扩展程序时，系统会将相应代码库注册为该扩展程序的规范来源。
  - 代码库中包含您的扩展程序的目录。
  - 您要基于其构建扩展程序版本源代码的提交的 Git 参考文档。这可以是提交的哈希、标记或分支名称。
- 您上传的版本所处的发布阶段。
  
  alpha、beta 和 rc（候选版本）是可上传的预发布版本阶段，供测试人员安装以进行测试。在首次上传一个新的扩展程序时，请使用上述某种阶段。
  
  stable 是可在 Extensions Hub 上发布的公开版本阶段。上传 stable 版本会自动启动审核流程，如果审核通过，则会发布扩展程序。
请注意，您不必指定版本号，系统会从 extension.yaml 文件获取该值。在您上传扩展程序预发布版本时，相应阶段和上传编号会附加到该版本。例如，如果 extension.yaml 指定了版本 1.0.1，并且您上传了一个候选版本，则系统获得的版本为 1.0.1-rc.0；如果您又上传了同一版本的另一个候选版本，系统会自动递增版本计数，即会获得 1.0.1-rc.1，依此类推。

现在，您已经上传了该扩展程序的预发布版本，可以与他人共享该扩展程序以便进行测试。用户可以通过以下两种方式安装您的扩展程序：

通过控制台安装：用户可以点击以下格式的链接来安装相应的扩展程序：
```
https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version
```
您可以将该直接链接分享给测试人员。
通过 CLI 安装：用户可以使用 ext:install 命令并附加扩展程序 ID 字符串参数，来安装相应的扩展程序：
```
firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id
```

上传更新的版本

在上传扩展程序的第一个版本后，您可以上传更新来修复错误、新增功能或推进发布阶段。在您上传新版本后，Firebase 控制台会提示安装了旧版扩展程序的用户进行升级。

如需上传更新，请按以下步骤操作：

可选：将代码提交到一个公共 Git 代码库。
运行 Firebase CLI 的 ext:dev:upload 命令：
GitHub
```
firebase ext:dev:upload your_publisher_id/your_extension_id
```
这次系统不会提示您指定 GitHub 代码库或扩展程序根目录，因为系统已经为您的扩展程序配置过这些信息。如果您重构了代码库结构或迁移到了新的代码库，可以通过命令参数 --root 和 --repo 相应进行更改。
本地源代码
```
cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local
```

提交扩展程序以供发布

准备好公开发布扩展程序后，请按以下步骤操作：

将代码提交到一个公共 Git 代码库。（若要公开发布扩展程序，则必须执行此操作）。
运行 Firebase CLI 的 ext:dev:upload 命令，指定 stable 作为发布阶段：
```
firebase ext:dev:upload your_publisher_id/your_extension_id
```
如果您之前发布过扩展程序版本，那么上传新的稳定版会自动提交扩展程序以供审核。

如果您是在上传扩展程序的第一个稳定版，则需在发布商信息中心找到该扩展程序，然后点击发布到 Extensions Hub。

提交扩展程序后，审核过程可能需要几天的时间。如果审核通过，扩展程序便会发布到 Extensions Hub。如果发布申请遭拒，您会收到一条说明原因的消息；之后，您可以相应解决该消息中阐明的问题，并重新提交扩展程序以供再次审核。

为了加快审核速度并增加首次提交便通过审核的几率，请在提交之前仔细检查以下内容：

您已对扩展程序及其安装流程进行了全面测试。
您的文档完整无误，可以在 Firebase 控制台中正常呈现。
您的发布商名称及品牌信息清晰明确地表明您是发布商。
扩展程序的名称、说明和图标清晰明确地反映了扩展程序的用途。
您应用了准确有用的标签。
您在 extension.yaml 中声明了您使用的所有 Google API 及非 Google API，以及您的扩展程序发出的所有事件类型。
您只会向用户申请获得正常运行扩展程序所需的角色访问权限，并向用户明确说明您为何需要此类访问权限。
您的源文件明确遵循 Apache-2.0 许可条款。

管理自己上传和发布的扩展程序

列出自己上传的扩展程序

如需列出您在自己的发布商 ID 下上传的扩展程序，请执行以下操作之一：

发布商信息中心

在发布商信息中心查看扩展程序。

Firebase CLI

运行 ext:dev:list 命令：

firebase ext:dev:list your_publisher_id

查看自己上传的扩展程序的使用情况

如需查看您在自己的发布商 ID 下上传的扩展程序的使用情况，请执行以下操作之一：

发布商信息中心

发布商信息中心包含所有扩展程序的累计使用情况指标以及每个扩展程序的单独指标。

Firebase CLI

运行 ext:dev:usage 命令：

firebase ext:dev:usage your_publisher_id

弃用扩展程序的某个版本

在某些情况下，您可能希望弃用扩展程序的旧版本。例如，如果您发布了一个修复重大问题或更新重要安全依赖项的新版本，便很有必要阻止新用户安装旧版本，并鼓励现有用户升级到新版本。

如需弃用扩展程序的某个版本，请执行以下操作之一：

发布商信息中心

在发布商信息中心点击扩展程序以打开其详细信息视图。
选择您要弃用的版本。
点击弃用版本。

Firebase CLI

运行 ext:dev:deprecate 命令：

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

您可以指定单个版本，也可以指定版本范围。示例：

1.0.2
1.1.0-1.1.7
<1.2.0
1.1.*

已弃用的扩展程序版本不会在 Extensions Hub 上列出，也不提供安装。如果用户的项目安装了已弃用的版本，系统会向他们显示一条消息，提示他们进行升级；不过在此期间，他们仍可以使用和重新配置该扩展程序。

如果一个扩展程序的每个版本都被弃用，系统会将该扩展程序本身视为已被弃用，并将其从 Extensions Hub 移除。之后，如果上传已弃用扩展程序的新版本，系统会自动启动审核流程，并在审核通过后将其重新发布到 Extensions Hub 上。

如需撤消弃用，请使用发布商信息中心，或运行 Firebase CLI 的 ext:dev:undeprecate 命令：

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

附录：构建错误问题排查

在您上传扩展程序时，后端会首先按照以下步骤构建您的源代码：

克隆 GitHub 代码库并检出指定的源代码引用。
在 extension.yaml 中指定的每个函数源目录中运行 npm clean-install 以安装 NPM 依赖项（请参阅 Cloud Functions 资源中的 sourceDirectory）。

请注意以下几点：
- 每个 package.json 文件都必须有一个相应的 package-lock.json 文件。如需了解详情，请参阅 npm-ci。
- 在安装依赖项期间，系统不会运行安装后脚本。如果您的源代码 build 依赖于安装后脚本，请先重构代码，再进行上传。
在 extension.yaml 中指定的每个函数源目录中运行 npm run build 以构建代码。

只有扩展程序的根目录才会保存在将要分享的最终扩展程序软件包中。

如果您在上传扩展程序时遇到构建错误，请在本地的一个全新目录中重复上述构建步骤，直到不再出错，然后尝试重新上传。