用 build 命令产出生产环境扩展产物

​

什么时候使用 build

• 为 Chrome Web Store、Edge Add-ons 或 Firefox Add-ons 准备扩展包。
• 在持续集成（CI）中跑出可复现的生产产物。
• 在提交前验证生产打包的输出以及各浏览器目标之间的差异。

​

build 命令的能力

​

用法

extension build [project-path] [options]

extension build [project-path] [options]

extension build [project-path] [options]

extension build [project-path] [options]

extension build [project-path] [options]

​

build 输出

dist/
├── chrome/
│   ├── manifest.json
│   ├── background/service_worker.js
│   ├── content_scripts/content-0.js
├── edge/
│   ├── manifest.json
│   ├── background/service_worker.js
│   ├── content_scripts/content-0.js

​

浏览器目标矩阵

​

引擎目标对 build 意味着什么

• 独立的输出目录。 --browser=chromium-based 输出到 dist/chromium-based，与 dev、preview、start 在该目标下使用的目录一致——用自定义 Chromium 二进制开发的项目，构建产物路径完全对应。
• 独立的 env 解析。 .env.chromium-based 与 .env.chromium-based.production 优先于家族级的 .env.chromium/.env.chrome/.env.edge，且打包后的代码中 EXTENSION_BROWSER === "chromium-based"——代码与配置可以据此区分“通用 Chromium”与某个具体商店构建。
• 独立的 manifest 前缀。 manifest.json 中的 chromium-based: 键会作为该目标最具体的匹配生效，叠加在家族级 chromium: 键之上。chrome: 与 edge: 键不适用。

​

参数与 flag

​

Safari flag

​

共享的全局选项

​

模式覆盖

extension build ./my-extension --mode development

extension build ./my-extension --mode development

extension build ./my-extension --mode development

extension build ./my-extension --mode development

extension build ./my-extension --mode development

​

zip 行为

​

示例

​

带 zip 输出与自定义文件名的构建

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

​

带 polyfill 支持的构建

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

​

构建源代码与产物 zip

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

​

成功的构建会打印什么

⏵⏵⏵ Extension built for production in dist/chrome (35.5 KB).
⏵⏵⏵ Send this build to someone for review: https://docs.extension.dev/share/unpublished-build-for-review

​

用 --output json 输出机器可读结果

• 成功的运行会打印一个 status: "built" 帧。它的 value 携带构建出的浏览器、解析出的模式，以及每个浏览器一份汇总。每份汇总记录输出路径、资源总量、警告文本，以及相关时的 Safari 应用标识。
• 失败的构建会在进程以 1 退出前打印一个 ok: false 帧，其 status: "build-failed"、error.code: "E_COMPILE"。

​

Firefox 构建的商店检查

Store check for addons.mozilla.org: addons-linter found 1 error and 2 warnings in dist/firefox
AMO <error|warning> <CODE>: <message> (<file>:<line>)

Skipped the addons.mozilla.org lint: addons-linter is not installed. Install it with: npm install -D addons-linter or pass --no-addon-lint to silence this.

​

面向 Opera Add-ons 的可读输出

Opera Add-ons reviews readable source, so this build does not minify first-party code. Pass --minify to minify it anyway.

​

最佳实践

• 查看构建日志： 每次构建后检查日志，看是否有警告与缺失资源。
• 优化你的 manifest： 让 manifest.json 与每个目标浏览器都兼容。
• 有意识地命名产物： 用 --zip-filename 让 CI 产物命名保持稳定。
• 逐个目标验证输出： 发布前检查每一个 dist/<browser> 目录。之后的一次 dev 会用带开发插桩的构建覆盖同一个目录，那个构建会额外加上 scripting、tabs、management、storage 等权限，把你的 content script 的匹配模式合并进 host_permissions，并把 hot/* 与 extension-js-control.json 列为只对这些匹配开放的 web-accessible resources。没有 content script 的项目不会得到后两项。打包或发布前请重新运行一次 build。

​

下一步

• 把这个构建通过一个链接交给别人评审，参见 Share an unpublished build for review。
• 把产物提交到浏览器商店，参见 extension.dev 发布文档。
• 用 publish 为项目在 extension.dev 上获取一个可分享的 URL。
• 用 preview 运行已有的构建产物。
• 用 start 一条命令构建并启动。
• 在 extension.config.js 中集中配置共享默认值。
• 在 环境变量 中查看配置期的 env 加载行为。
• 在 可用浏览器 中查看支持的目标。