build 会以生产模式编译你的扩展,并将输出写入 dist/<browser>。
对于 monorepo / 子模块项目,关于配置期的环境变量解析(优先项目根,再退回工作区根),请参见 环境变量。
什么时候使用 build
- 为 Chrome Web Store、Edge Add-ons 或 Firefox Add-ons 准备扩展包。
- 在持续集成(CI)中跑出可复现的生产产物。
- 在提交前验证生产打包的输出以及各浏览器目标之间的差异。
build 命令的能力
用法
build 输出
运行build 后,Extension.js 会为所选浏览器目标生成优化过的文件。输出位于 dist/,每个目标一个子目录。每个目录都包含打包后的 JavaScript、CSS、HTML 和必要的运行时资源。
对于 TypeScript 项目,
build 也会重新生成 extension-env.d.ts
环境类型声明(与 dev 写出的是同一个文件),
所以无论你之前是否运行过 dev,CI 上的 tsc --noEmit 都能保持干净。 纯
JavaScript 项目会跳过这一步。ready.json 记录真实路径。
在 dev 会话旁边构建
extension dev 与 extension build 都会写入 dist/<browser>。当同一浏览器的 dev 会话正在运行时,向该文件夹构建会被拒绝,并报 E_DEV_SESSION_DIST_SHARED,不会写入任何内容。消息会给出该会话的进程 id,并指向 --out-dir。
要在 dev 窗口保持打开的同时测试或打包一份生产构建,请传入 --out-dir。构建会写到 <path>/<browser>,并把 zip 放在 <path>/ 下:
build/chrome 与 build/<name>-<version>-chrome.zip,而 dist/chrome 保持 dev 会话留下的状态。同样的设置也可以写进 extension.config.js 的 commands.build.outDir。
浏览器目标矩阵
引擎目标对 build 意味着什么
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:键不适用。
gecko-based 相对 firefox 的行为完全相同。构建不需要浏览器二进制——--chromium-binary/--gecko-binary 只对会启动浏览器的命令有意义。
参数与 flag
--author 与 --author-mode 是 --debug 的隐藏、已废弃别名。
Safari flag
这些 flag 只适用于safari 与 webkit-based 目标。把其中任何一个和别的目标一起传入都会以错误退出,所以拼错时不会静默地什么都不做。
Safari 打包会在构建前跑一次预检。在非 macOS 主机上,
build 会告警并跳过 Safari 打包步骤,但仍然会编译 bundle。在 macOS 上,如果 Xcode 缺失或损坏,则是致命错误。
共享的全局选项
也支持 全局 flag。模式覆盖
--mode 会覆盖构建的打包器模式以及 NODE_ENV。可选值为 development、production 或 none。当你需要为 staging 或调试产出非生产 bundle 时(类似 Vite / webpack 的工作流),可以用它来对齐行为。
production。
development 模式的构建是可以直接发布的。它保留你在 manifest 里写的 CSP 与权限,不注入任何 reload 客户端,它的 zip 里也不包含 source map(.map 文件会留在 dist/<browser> 里供你使用)。只有 extension dev 会打开 dev 检测。--zip 在任何模式下都会打包输出,而不只是 production。
zip 行为
每个 zip 都落在
dist/ 里,与 dist/<browser> 目录并列而不是放在它里面,因为 dist/<browser> 是商店上传或 load-unpacked 整个取走的目录。不带 --zip-filename 时,名称由 manifest 的 name 转小写、去掉 a-z0-9 与空格以外的所有字符、把剩下的空格换成连字符,再接上 manifest 的 version 和浏览器得到。一个名为 My Extension+、版本为 1.0.0 的 manifest 会打包成 dist/my-extension-1.0.0-chrome.zip。因为名称被改写过,请从构建输出里读取实际路径,而不要用 manifest 名称自行拼接。在 --output json 下,每个归档都会列在 zip_artifacts 里,带有路径和大小。
--zip-filename 同时命名两个归档,而且分发归档总会追加浏览器名,所以在不同运行里用同一个名字构建两个浏览器时,彼此不会互相覆盖。在 Chrome 构建里传入 --zip-filename=review-bundle.zip 与 --zip-source 会写出 dist/review-bundle-chrome.zip 与 dist/review-bundle-source.zip。源代码归档对每个浏览器都一样,所以它的名字不带浏览器,一次构建只写一个源代码归档。已经以浏览器名结尾的名字会保持原样。--browser=edge,chrome --zip-filename=my-extension.zip 会写出 dist/my-extension-edge.zip 与 dist/my-extension-chrome.zip。
从 4.1.39 之后的版本起,--zip-dir <path> 决定 ZIP 文件写到哪个文件夹。路径相对于项目根目录,也可以是绝对路径。--zip-dir release 会写出 release/my-extension-1.0.0-chrome.zip,源代码归档也落在同一个文件夹里。同样的设置可以写进 extension.config.js,键是 commands.build.zipDir。
有两种路径会让构建报错并停止。一种是离开项目的相对路径,例如 ../release。要写到项目之外,请传绝对路径。另一种是 dist/<browser> 里面的文件夹,因为那个文件夹是整个发布出去的。
--zip-filename 只决定名称。值里带的文件夹会被去掉,所以在 Chrome 构建里传 --zip-filename=out/review.zip,文件名是 review-chrome.zip。
从 4.2.0 之后的版本起,编译失败时不会创建 ZIP 文件,因为 dist/<browser> 里仍是上一次的构建。ZIP 文件无法写入时,构建以 E_ZIP_SKIPPED 失败,结尾的 Build failed with 1 error. 会补充说明输出文件夹已就位,可以按构建结果加载。
生产构建的 source map
生产构建不写 source map。从 4.1.39 之后的版本起,--source-maps 会在 dist/<browser> 里的每个脚本和样式表旁边写出一个 .map 文件:
dist/<browser> 里供你使用,所以你可以读懂已发布构建抛出的堆栈。在 extension.config.js 里设置 commands.build.sourceMaps: true,每次构建都会写出它们。默认值是 false。
示例
带 zip 输出与自定义文件名的构建
dist/my-extension-edge.zip 与 dist/my-extension-chrome.zip,因为每个分发归档都会追加浏览器名,即使只构建一个目标也一样。
带 polyfill 支持的构建
构建源代码与产物 zip
成功的构建会打印什么
在资源汇总之后,一次成功的构建会打印输出目录和它的体积。 生产构建随后会打印产出它的 Node.js、包管理器与 Extension.js 版本, 让商店审核人员可以重新构建这个包并得到相同的字节:pnpm build)启动时,版本行中才会出现包管理器。
从 4.1.39 之后的版本起,那一行里的体积只统计发布出去的文件。source map 单独统计,那一行会说明有多少没有进入 ZIP 文件:
compiled with 1 warning in 316 ms, listed below.,而不是 compiled in。
4.2.0 之前的版本打印 compiled with warnings,所以匹配那段文字的脚本必须改为匹配计数的形式。
从 4.1.41 之后的版本起,在插件的 done 钩子中失败的构建不会打印 compiled in 那一行。
从 4.2.0 之后的版本开始,失败的构建也会打印警告详情,和成功的构建一样。4.2.0 及之前的版本只在设置 EXTENSION_VERBOSE=1 时才打印失败构建的警告。
从 4.1.39 之后的版本起,如果一个文件被多个入口导入,它产生的警告或错误只打印一次,也只计数一次。
当输出不是终端,或者设置了 NO_COLOR 时,打包器的错误和警告也会以纯文本打印,build 和 dev 都是如此。FORCE_COLOR=1 保留颜色,FORCE_COLOR=0 关闭颜色。
不要用这些文案来给 CI 把关。它是写给人看的,会随版本变化。
请使用退出码,或者下面的 --output json,那才是受支持的机器契约。
用 --output json 输出机器可读结果
--output json 会在 stdout 上打印一个 schema-1 信封,并把给人看的构建日志转到 stderr。stdout 始终可以作为一份 JSON 文档解析。
- 成功的运行会打印一个
status: "built"帧。它的value携带构建出的浏览器、解析出的模式,以及每个浏览器一份汇总。每份汇总记录输出路径、资源总量、警告文本,以及相关时的 Safari 应用标识。当能解析出错误码时,每个警告字符串都以W_CODE:开头,例如W_CSS_DEAD_REF: ...,与logs和uninstall的约定相同。 - 失败的构建会在进程以
1退出前打印一个ok: false帧,其status: "build-failed"。编译错误带error.code: "E_COMPILE",并且error.details会列出失败背后的每条诊断,各自带有错误码、文件和位置,错误排在前面,上限 20 条,截断时设置truncated: true。见编译诊断。项目目录不存在带E_PROJECT_NOT_FOUND,目录里没有 manifest 带E_MANIFEST_NOT_FOUND,manifest 无法解析带E_MANIFEST_INVALID。配置文件加载失败带E_CONFIG_LOAD。 - 路径参数是远程 URL 时,下载进度行同样写到 stderr。返回的不是 ZIP 归档、归档已损坏或含有位于其文件夹之外的条目带
E_REMOTE_ZIP_INVALID,超时带E_REMOTE_FETCH_TIMEOUT,连接被拒绝或 HTTP 错误带E_REMOTE_DOWNLOAD。含有位于其文件夹之外的条目的归档会在写入任何内容之前被拒绝,消息会点名该条目。 - 从 4.2.0 之后的版本起,被
SIGINT或SIGTERM停止的构建会打印一个带E_INTERRUPTED和value.signal的stopped帧,并以130或143退出。上一次构建的输出保持原样。文本模式下,构建以同样的退出码退出,并且不在 stdout 上打印任何内容。 - 从 4.2.0 之后的版本起,一旦
build打印出扩展已构建完成,Ctrl+C或SIGTERM就不再停止它。运行以退出码0结束,--output json运行以它自己的构建完成帧结束。当--browser列出多个浏览器时,这从最后一个浏览器的那一行起成立。在那一行之前的信号仍然以130或143退出,并保留之前的输出。 在--output json之外,它还会打印一行:The build had already finished, so there was nothing to stop.
- 警告字符串以
W_*错误码开头。更早的版本使用E_*名称。 - 在创建编译器时抛错的插件(例如在它的
apply中)带E_COMPILE_FATAL。 - 以空消息抛出的错误会指出抛出它的文件、行和列。
- 构建仍在查找项目及其浏览器时的拒绝,不会在 stderr 上打印任何内容。
- 之后的每个失败还会在 stderr 上打印给人看的行。
- 失败构建的帧会像成功构建一样,在
warnings中列出构建遇到的带错误码的警告,每个一次。
dist/extension-js/<browser>/build-summary.json。通过 shell 调用 extension build 的脚本可以从那里读取结构化的警告。请检查文件的修改时间,避免读到过期文件。
从 4.1.39 之后的版本起,每份汇总里的 total_assets、total_bytes 和 largest_asset_bytes 只统计发布出去的文件。写出了 source map 的构建会用 source_map_assets 和 source_map_bytes 单独报告它们。没有写出 source map 的构建不带这两个字段。
Firefox 构建的商店检查
从 4.1.18 开始,面向 Gecko 目标(firefox、gecko-based 以及各 Gecko 分支)的生产构建会在项目里装有 addons-linter 时,用它检查 dist/<browser>。这个 linter 正是 addons.mozilla.org 审核提交时运行的工具,所以这项检查能在你上传之前暴露出会被拒绝的问题。
每一条发现都以警告形式打印。构建永远不会因此失败,退出码保持为 0。先打印一行汇总,然后每条发现各占一行,带上 linter 的代码、消息和位置:
npx addons-linter dist/firefox 查看完整报告。运行超过 10 秒的 linter 会被放弃,构建在没有这项检查的情况下继续。
落在打包了依赖的 chunk 里的发现会标注归属,因为单看文件名可能指向错误的作者。当该 chunk 里没有你自己的代码时,这一行以 - this file is bundled dependency code (react, react-dom), not yours 结尾。当该 chunk 两者混合时,以 - this file also bundles react, react-dom, so the finding may be theirs 结尾。
当没有安装 addons-linter 时,构建会为每个项目打印一行 info 并跳过检查:
npx addons-linter,因为那会运行同一份坏掉的副本。
当发现的问题落在打包进来的包里时,检查会在浏览器文件夹旁边写出 amo-reviewer-note.md,例如 dist/amo-reviewer-note.md。把其中打包库的部分粘贴到提交中。从 4.1.41 之后的版本起,lint 没有跑完的构建会把上一份说明移到 amo-reviewer-note.stale.md。找不到 linter 的构建也会这样做,并在那一行里说明。
用 --no-addon-lint,或在 extension.config.js 中设置 commands.build.addonLint: false,即可关闭检查。非生产模式会跳过它,因为开发产物带有仅供开发的授权,linter 会白白地标记它们。extension start 也会跳过它,因为 start 是预览构建,而不是发布构建。
Firefox 构建会拆分大文件
addons.mozilla.org 不解析 5 MB 及以上的脚本,商店检查遇到这样的文件就会失败。从 4.1.39 之后的版本起,面向 Gecko 目标的构建会把它能拆分的文件限制在 4 MB 源码以内。Chrome、Edge 和 Safari 的输出不变。
页面会在自己的 HTML 里列出每个部分,所以被拆分的页面不需要你做任何改动。面向 Firefox 构建时,不要在自己的代码里写死
action/index.js 或 shared/commons.js。
对于超过限制的单文件脚本,商店检查会报告 FILE_TOO_LARGE,这一行的结尾给出修复办法:用动态 import() 加载那个大依赖,让它作为低于限制的独立文件输出。如果没有安装 addons-linter、它没有给出结果,或者你用 --no-addon-lint 或 commands.build.addonLint: false 关闭了检查,构建会在以 Firefox build: 开头的一行里打印同样的修复办法。同一个文件不会在两种行里都被报告:
optimization.splitChunks 的一部分。可以在 config 钩子里修改它,见 Rspack 配置。
面向 Opera Add-ons 的可读输出
Opera 的审核标准要求审核者能读懂代码:扩展自身的代码若被压缩或混淆会被拒绝,第三方库则可以保持压缩。因此生产模式下的extension build --browser=opera 不做压缩,并打印一行提示:
--minify 可以覆盖这一默认值,也可以在 extension.config.js 中设置 commands.build.minify。同一个选项对其他目标反向生效:当审核者要求时,--no-minify 会让 Chrome 或 Firefox 构建保持可读。
最佳实践
- 查看构建日志: 每次构建后检查日志,看是否有警告与缺失资源。
- 优化你的 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 加载行为。
- 在 可用浏览器 中查看支持的目标。

