> ## 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`      |