> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 取得你的 Firefox Add-ons 憑證

> 建立 AMO 開發者帳號、接受發佈協議，並產生自動化提交 Firefox Add-ons 所需的 JWT issuer 與 secret。

自動化提交 Firefox Add-ons（AMO）需要一組憑證，而且在大多數情況下還需要一個識別碼：

| 值                      | 長什麼樣                                                                          | 從哪裡取得            |
| ---------------------- | ----------------------------------------------------------------------------- | ---------------- |
| JWT issuer（API key）    | `user:12345678:987`                                                           | AMO 的 API key 頁面 |
| JWT secret（API secret） | 64 個十六進位字元，只顯示一次                                                              | 與 issuer 一起產生    |
| 附加元件 GUID              | `{c1b2a3d4-0000-4000-8000-a1b2c3d4e5f6}`，或形如 `my-addon@example.com` 的電子郵件式 ID | 你的附加元件在開發者中心的頁面  |

## 先決條件

1. 建立一個 [Firefox 帳號](https://accounts.firefox.com)，並在
   [addons.mozilla.org](https://addons.mozilla.org) 登入。
2. 接受 Firefox Add-on Distribution Agreement。在你接受之前，API key
   頁面都會被鎖住——即使這個帳號已經透過網頁介面發佈附加元件很多年了。

## 產生 API 憑證

1. 開啟
   [AMO API key 頁面](https://addons.mozilla.org/developers/addon/api/key/)。
2. 產生新的憑證。
3. 複製 **JWT issuer**。它的形式是 `user:12345678:987`。多數工具口中的
   API key 指的就是這個值。
4. 立刻複製 **JWT secret**。

<Warning>
  JWT secret 只會顯示一次。如果你弄丟了，就只能重新產生一組憑證，而這會讓舊的那一組在所有正在使用它的地方失效。
</Warning>

## 附加元件 GUID 與第一次提交

GUID 的規則取決於發佈頻道：

* **Listed**（在 AMO 上公開上架）：必須已經有一個 GUID。請先在
  [開發者中心](https://addons.mozilla.org/developers/) 手動完成第一次提交，
  之後再自動化後續更新。
* **Unlisted**（簽署後自行發佈）：第一次提交時把 GUID 留空，AMO
  會建立一個新的附加元件並指派 GUID。

<Warning>
  GUID 留空這個便利只有一次機會，而且沒有任何東西會幫你把指派到的 GUID
  寫回去。第一次 unlisted 提交之後，請到開發者中心開啟這個附加元件的頁面，複製指派到的
  GUID，並存進你的 store 設定。之後每一次 GUID 為空的提交，都會再建立一個全新的附加元件，而不是更新第一個。
</Warning>

請明確設定發佈頻道。未設定的頻道會在提交時回退成 `listed`，結果不是失敗（沒有
GUID），就是發佈出一個你未必想要的公開上架（有設定 GUID）。

## 新附加元件的 manifest 要求

新的附加元件必須在 manifest 中宣告資料蒐集權限，否則 AMO 會拒絕這次提交：

```json theme={null}
{
  "browser_specific_settings": {
    "gecko": {
      "data_collection_permissions": { "required": ["none"] }
    }
  }
}
```

自 2025-11-03 起，AMO 對每一次新提交都要求這個鍵。你不必等到上傳時才發現被拒絕：當解析後的
Gecko manifest 缺少
`browser_specific_settings.gecko.data_collection_permissions` 時，針對 Firefox
目標的正式版建置會發出警告。

只有在擴充功能確實不傳輸任何資料時才使用 `["none"]`。這份宣告、[STORE.md](/docs/workflows/store-metadata)
的隱私章節與程式碼三者必須一致。完整規則請見
[Firefox 商店就緒](/docs/features/multi-platform-builds#firefox-store-readiness-data-collection-permissions)。

## 打包建置所需的原始碼 zip

當上傳的內容經過壓縮或打包時，AMO 會要求提供原始碼 zip——Extension.js
的正式版建置正屬於這種情況。用下面的指令產生：

```bash theme={null}
npx extension build --browser firefox --zip --zip-source
```

請在 `STORE.md` 的審查者說明章節裡講清楚如何從原始碼建置。

## 影響範圍與輪替

<Warning>
  AMO API 憑證是帳號層級的。這組 issuer 與 secret
  可以上傳到你帳號控制的每一個附加元件。如果你替多個客戶管理附加元件，請把每個客戶的附加元件放在該客戶自己的
  AMO 帳號底下。
</Warning>

AMO 憑證沒有預定的到期時間。輪替的方式是在 API key
頁面產生新的一組，這會撤銷舊的那一組，然後把新值重新填進所有存放過它們的地方。

## 名稱對照

每個值對應的環境變數：

| 值          | 環境變數                   |
| ---------- | ---------------------- |
| JWT issuer | `FIREFOX_JWT_ISSUER`   |
| JWT secret | `FIREFOX_JWT_SECRET`   |
| 附加元件 GUID  | `FIREFOX_EXTENSION_ID` |
| 發佈頻道       | `FIREFOX_CHANNEL`      |