每个扩展程序都必须提供一些文档来向用户说明扩展程序的用途和使用方法。
必须至少提供下面三个 Markdown 文件：
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
此外，您还应考虑生成下面的文档：
- 要上传至扩展程序公共代码库的
README文件。 - 您可以在自己的网站上发布并在
PREINSTALL.md中链接的详尽教程、指南和参考文档。
如需了解一些最佳实践以及常用的短语和结构，我们建议您参考官方 Firebase 扩展程序提供的文件。
创建 README 文件
您的扩展程序目录可以选择包含 README。请注意，firebase ext:dev:init 命令不会自动为您生成该文件。
但是，Firebase CLI 支持使用以下便捷命令自动生成 README 文件，其中包含从 extension.yaml 文件和 PREINSTALL.md 文件中拉取的内容：
firebase ext:info ./path/to/extension --markdown > README.md
官方 Firebase 扩展程序的所有 README 文件都是使用此命令生成的。
添加安装信息
编写或生成 README 文件后，向其添加安装信息。您可以使用以下代码段作为模板：
--- ## 🧩 Install this extension ### Console [][install-link] [install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name ### Firebase CLI ```bash firebase ext:install publisher_id/extension_name --project=[your-project-id] ``` > Learn more about installing extensions in the Firebase Extensions documentation: > [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console), > [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli) ---
编写 PREINSTALL 文件
PREINSTALL 文件是扩展程序的概览，是一种“营销”页面。
此文件中包含哪些内容？
- 扩展程序功能的全面说明。
- 前提条件列表，例如数据库设置或对非 Google 服务的访问权限（示例）
- 所有预安装任务的简要介绍及其说明
- 所有安装后任务的简要说明（示例）（详细说明请参阅
POSTINSTALL） - 结算可能带来的所有影响的简要说明（从样板文本开始）
用户会在何处看到此内容？
Firebase 控制台"> 中的预安装内容图片
Firebase 控制台"> 中的预安装内容大图
- 扩展程序页面上的 extensions.dev 部分。
- 扩展程序的源代码库（在扩展程序目录中）
- 在扩展程序的 README 文件中（如果您使用 Firebase CLI
--markdown > README.md
PREINSTALL 文件无法访问扩展程序的参数值，因此不能保证参数引用以实际值呈现。
有哪些最佳实践？
- 如果可以，请将
PREINSTALL文件的全部内容保留在一页中 - 请提供扩展程序安装之前最终用户须知事项的详细程度
- 将详细说明放在
POSTINSTALL文件或其他补充文件中 - 简要说明您是否提供其他工具或脚本来支持该扩展程序
写入 POSTINSTALL 文件
POSTINSTALL 文件是扩展程序的详细安装后说明页。
此文件中包含哪些内容？
- 所有需执行的安装后任务的详细说明，例如设置 Firebase 安全规则或添加客户端代码（示例）
- 关于如何立即试用已安装的扩展程序的一般说明（例如“前往控制台，然后执行此操作”）
- 有关如何触发扩展程序的基本信息，尤其是针对 HTTP 请求触发的扩展程序
- 有关如何监控已安装的扩展程序的简要说明（从样板文本开始）
用户会在何处看到此内容？
Firebase 控制台"> 中的安装后内容图片
Firebase 控制台"> 中的安装后内容大图
当用户安装完扩展程序后，此内容会显示在 Firebase 控制台中（在已安装的扩展程序的详细信息卡片中）
- 请务必在实际项目中安装扩展程序，检查是否显示
POSTINSTALL内容
- 请务必在实际项目中安装扩展程序，检查是否显示
扩展程序的源代码库（在扩展程序目录中）
POSTINSTALL 文件可以访问该扩展程序的参数值和多个函数相关变量。当 Firebase 控制台中显示 POSTINSTALL 内容时，将显示实际值，而不是参数或变量引用。下文详细介绍了如何在 POSTINSTALL 文件中引用参数和变量。
有哪些最佳实践？
- 确保
POSTINSTALL文件的所有内容简洁明了、描述清晰。 - 使用标题对内容进行划分，拆分不同的任务或概念。
- 不妨在您的网站上（示例）或在扩展程序代码库中的补充 Markdown 文件中（示例）发布特定工作流或任务的详细说明。
- 引用参数以及与函数相关的变量，以便用户在说明的上下文中查看已配置的值
引用参数和变量
安装后，Firebase 控制台会显示该扩展程序的 POSTINSTALL 文件内容。如果您在 POSTINSTALL 文件中引用参数和与函数相关的变量（见下表），则控制台会使用已安装的实例的实际值填充这些引用。
使用以下语法访问 POSTINSTALL 文件中已配置的参数值：${param:PARAMETER_NAME}
您还可以仅在 POSTINSTALL 文件中引用以下与函数相关的变量。Firebase 支持这些变量，因此您可以更轻松地为用户提供安装后的指导。它们仅可在 POSTINSTALL 文件中使用，因为这些变量的值只有在安装后才可用。
在下表中，function-name 是 extension.yaml 中函数资源对象的 name 字段的值。
| 函数相关变量的参考 | 说明 | 变量值（扩展程序安装后由 Firebase 自动填充） |
|---|---|---|
${function:function-name.location}
|
||
| 位置（函数的部署位置） | 示例值：us-central1 |
|
${function:function-name.name}
|
||
| 最终部署的函数的名称，其中包括扩展程序的实例 ID |
通用格式： 示例值： |
|
${function:function-name.url}
（仅适用于 HTTP 函数） |
||
| 最终部署的函数的网址，客户端代码可以向其发出 HTTP 请求 |
通用格式：
示例值： |
|
介绍如何触发扩展程序的文档
在扩展程序的用户文档中，您需要指导用户如何触发扩展程序。您可以根据需要细化这些说明，但请注意编写POSTINSTALL文件的最佳做法。如需查看关于如何提供这些说明的指导，请展开下面适合您的扩展程序的部分。
编写 CHANGELOG 文件
此文件中包含哪些内容？
每个扩展程序都必须提供一个 CHANGELOG.md 文件，用于记录您发布的扩展程序的每个新版本所包含的更新内容。将每个版本放在第 2 级标题 (##) 下；或者，您也可以使用自己偏好的任何 Markdown 格式。
以下示例摘自某个官方扩展程序：
## Version 0.1.3 feature - Support deletion of directories (issue #148). ## Version 0.1.2 feature - Add a new param for recursively deleting subcollections in Cloud Firestore (issue #14). fixed - Fixed "cold start" errors experienced when the extension runs after a period of inactivity (issue #48). ## Version 0.1.1 Initial release of the _Delete User Data_ extension.
用户会在何处看到此内容？
- 当用户升级到您的扩展程序的新版本时，此内容会显示在 Firebase 控制台和 CLI 中。Firebase 控制台和 CLI 只会显示用户完成当前升级后生效的更新内容。
- 扩展程序的源代码库（在扩展程序目录中）。