跳转到主要内容
为一个或多个浏览器目标生成生产环境扩展产物。 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 项目会跳过这一步。
输出结构示例:
从 4.1.41 之后的版本开始,通过符号链接访问的项目,构建出的字节与用真实路径构建的相同。打印的路径保留你输入的路径,而 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 文件:
这些 map 从不进入 ZIP 文件。它们留在 dist/<browser> 里供你使用,所以你可以读懂已发布构建抛出的堆栈。在 extension.config.js 里设置 commands.build.sourceMaps: true,每次构建都会写出它们。默认值是 false。

示例

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

在这个示例中,构建以 Edge 与 Chrome 为目标,并对两个输出进行打包。归档会保存为 dist/my-extension-edge.zip 与 dist/my-extension-chrome.zip,因为每个分发归档都会追加浏览器名,即使只构建一个目标也一样。

带 polyfill 支持的构建

在这个示例中,构建以 Chrome 与 Firefox 为目标,并在相关地方加入 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.
从 4.1.41 之后的版本起:
  • 警告字符串以 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 的代码、消息和位置:
输出最多打印 20 条发现,linter 最多运行 10 秒。超过 20 条时,会有一行说明还有多少条没显示,并指向 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 并跳过检查:
安装命令会按你项目使用的包管理器来措辞。 从 4.1.41 之后的版本起,已安装但无法加载的 linter 会单独打印一行。这一行指出那份副本和原因,并建议重新安装,而不是运行 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: 开头的一行里打印同样的修复办法。同一个文件不会在两种行里都被报告:
这个上限是 Gecko 目标默认 optimization.splitChunks 的一部分。可以在 config 钩子里修改它,见 Rspack 配置。

面向 Opera Add-ons 的可读输出

Opera 的审核标准要求审核者能读懂代码:扩展自身的代码若被压缩或混淆会被拒绝,第三方库则可以保持压缩。因此生产模式下的 extension build --browser=opera 不做压缩,并打印一行提示:
构建会对整个产物关闭压缩,包括依赖在内,因为一个打包后的 chunk 可能把你的代码和依赖的代码混在一起。传入 --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。

下一步