WXT 中文文档

Appearance

发布 ​

WXT 可以将你的扩展打包为 ZIP 文件，并提交到各个商店进行审核或用于自托管。

首次发布 ​

如果你是第一次将扩展发布到商店，需要手动完成整个流程。WXT 不会帮你创建商品列表，每个商店都有独特的步骤和要求，你需要自行熟悉。

有关各商店的具体详情，请参阅下方的商店章节。

自动化 ​

WXT 提供了两个命令来帮助自动化提交新版本进行审核和发布：

  • wxt submit init：设置 wxt submit 命令所需的所有密钥和选项
  • wxt submit：提交扩展的新版本进行审核（审核通过后自动发布）

首先，运行 wxt submit init 并按照提示操作，或者运行 wxt submit --help 查看所有可用选项。完成后，你应该会有一个 .env.submit 文件！WXT 将使用此文件来提交你的更新。

在 CI 环境中，请确保将所有环境变量添加到提交步骤中。

要提交新版本进行发布，请先构建所有计划发布的 ZIP 文件：

sh
wxt zip
wxt zip -b firefox

然后运行 wxt submit 命令，传入所有要发布的 ZIP 文件。在本例中，我们将向所有 3 个主要商店发布：Chrome Web Store、Edge Addons 和 Firefox Addons Store。

如果这是你第一次运行该命令，或者你最近对发布流程做了更改，建议通过传入 --dry-run 标志来测试你的密钥。

sh
wxt submit --dry-run \
  --chrome-zip .output/{your-extension}-{version}-chrome.zip \
  --firefox-zip .output/{your-extension}-{version}-firefox.zip --firefox-sources-zip .output/{your-extension}-{version}-sources.zip \
  --edge-zip .output/{your-extension}-{version}-chrome.zip

如果试运行通过，移除该标志并执行实际发布：

sh
wxt submit \
  --chrome-zip .output/{your-extension}-{version}-chrome.zip \
  --firefox-zip .output/{your-extension}-{version}-firefox.zip --firefox-sources-zip .output/{your-extension}-{version}-sources.zip \
  --edge-zip .output/{your-extension}-{version}-chrome.zip

WARNING

有关 --firefox-sources-zip 选项的更多详情，请参阅 Firefox Addon Store 章节。

GitHub Action ​

以下是一个 GitHub Action 示例，用于提交扩展的新版本进行审核。请确保已将工作流中使用的所有必需密钥添加到仓库的设置中。

yml
name: Release

on:
  workflow_dispatch:

jobs:
  submit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Zip extensions
        run: |
          pnpm zip
          pnpm zip:firefox

      - name: Submit to stores
        run: |
          pnpm wxt submit \
            --chrome-zip .output/*-chrome.zip \
            --firefox-zip .output/*-firefox.zip --firefox-sources-zip .output/*-sources.zip
        env:
          CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }}
          CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }}
          CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }}
          CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }}
          FIREFOX_EXTENSION_ID: ${{ secrets.FIREFOX_EXTENSION_ID }}
          FIREFOX_JWT_ISSUER: ${{ secrets.FIREFOX_JWT_ISSUER }}
          FIREFOX_JWT_SECRET: ${{ secrets.FIREFOX_JWT_SECRET }}

上面的 Action 为基本工作流奠定了基础，包括 zip 和 submit 步骤。要进一步增强你的 GitHub Action 并深入了解更复杂的场景，可以参考以下来自实际项目的示例。它们引入了版本管理、变更日志生成和 GitHub releases 等高级功能，适用于不同需求：

这些示例旨在提供清晰的参考，是自定义你自己工作流的良好起点。欢迎探索并根据你的项目需求进行调整。

商店 ​

Chrome Web Store ​

✅ 已支持 • 开发者控制台 • 发布文档

为 Chrome 创建 ZIP 文件：

sh
wxt zip

Firefox Addon Store ​

✅ 已支持 • 开发者控制台 • 发布文档

Firefox 要求你上传源代码的 ZIP 文件。这样他们可以重新构建你的扩展，并以可读的方式审核代码。更多详情可在 Firefox 的文档 中找到。

运行 wxt zip -b firefox 时，WXT 会同时打包你的扩展和源代码。某些文件（如配置文件、隐藏文件、测试文件和被排除的入口点）会自动从源代码中排除。但是，手动检查 ZIP 文件以确保它只包含重新构建扩展所需的文件仍然很重要。

要自定义哪些文件被打包，请在配置文件中添加 zip 选项。

ts
import { defineConfig } from 'wxt';

export default defineConfig({
  zip: {
    // ...
  },
});

如果你是第一次提交到 Firefox Addon Store，或者你更新了项目布局，请务必测试你的源代码 ZIP！以下命令应该能让你在解压后的 ZIP 中重新构建你的扩展。

sh
pnpm i
pnpm zip:firefox
sh
npm i
npm run zip:firefox
sh
yarn
yarn zip:firefox
sh
bun i
bun zip:firefox

确保你有一个 README.md 或 SOURCE_CODE_REVIEW.md 文件，其中包含上述命令，以便 Firefox 团队知道如何构建你的扩展。

确保在你的主项目中运行 wxt build -b firefox 和在打包的源代码中运行时，构建输出完全一致。

WARNING

如果你使用了 .env 文件，它们可能会影响输出目录中的 chunk 哈希值。要么在运行 wxt zip -b firefox 之前删除 .env 文件，要么使用 zip.includeSources 选项将其包含在源代码 zip 中。注意不要在 .env 文件中包含任何密钥。

详情请参阅 Issue #377。

私有包 ​

如果你使用了私有包，且不想在审核过程中向 Firefox 团队提供你的认证令牌，可以使用 zip.downloadPackages 下载所有私有包并将其包含在 zip 中。

ts
export default defineConfig({
  zip: {
    downloadPackages: [
      '@mycompany/some-package',
      //...
    ],
  },
});

根据你使用的包管理器，源代码 zip 中的 package.json 将通过 overrides 或 resolutions 字段被修改以使用下载的依赖。

WARNING

WXT 使用 npm pack <package-name> 命令来下载包。这意味着无论你使用什么包管理器，都需要正确设置 .npmrc 文件。NPM 和 PNPM 都遵循 .npmrc 文件，但 Yarn 和 Bun 有各自授权私有注册表的方式，因此你需要额外添加一个 .npmrc 文件。

Safari ​

🚧 暂不支持

WXT 目前不支持 Safari 的自动化发布。Safari 扩展需要一个原生 MacOS 或 iOS 应用包装器，而 WXT 目前尚未创建此功能。如果你想发布到 Safari，请参考以下指南：

运行 safari-web-extension-converter CLI 工具时，请传入 .output/safari-mv2 或 .output/safari-mv3 目录，而不是你的源代码目录。

sh
pnpm wxt build -b safari
xcrun safari-web-extension-converter .output/safari-mv2

Edge Addons ​

✅ 已支持 • 开发者控制台 • 发布文档

无需为 Edge 创建专门的 ZIP 文件。如果你已经发布到 Chrome Web Store，可以复用你的 Chrome ZIP 文件。

但是，如果你有专门针对 Edge 的功能，请使用以下命令创建单独的 ZIP：

sh
wxt zip -b edge