每個擴充功能都必須提供說明文件，向使用者介紹擴充功能的作用和使用方式。
最低限度的必要說明文件是這組三個 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 檔案可以存取擴充功能的參數值和多個函式相關變數。當 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}
|
||
| 最終部署函式的名稱，包含擴充功能的執行個體 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 只會顯示使用者完成升級後會生效的變更。
- 擴充功能的原始碼存放區 (位於擴充功能目錄中)。