每個擴充功能都必須提供說明文件，向使用者說明擴充功能的作用和使用方式。
必要的最低限度文件為這組三個 Markdown 檔案：
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
此外，您也應考慮製作以下內容：
- 擴充功能公開存放區的
README檔案。 - 在您自己的網站上發布較長篇幅的教學課程、指南和參考資料，並在
PREINSTALL.md中連結這些內容。
如要瞭解一些最佳做法和常見的詞彙和結構，建議您查看官方 Firebase 擴充功能提供的檔案。
建立 README
擴充功能目錄可選擇包含 README。請注意，firebase ext:dev:init 指令不會自動產生一個。
不過，Firebase CLI 支援下列便利指令，可自動產生含有從 extension.yaml 檔案和 PREINSTALL.md 檔案提取內容的 README 檔案：
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 檔案可存取擴充功能的參數值和多個與函式相關的變數。當 POSTINSTALL 內容顯示在 Firebase 主控台時，系統會顯示實際值，而非參數或變數參照。請參閱下文，進一步瞭解如何在 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}
|
||
| 最終 deployed 函式的名稱，其中包含擴充功能的執行個體 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 只會顯示使用者完成升級後會生效的變更。
- 擴充功能的原始碼存放區 (位於擴充功能目錄中)。