跳转到主要内容
为一个或多个浏览器目标生成生产环境扩展产物。 build 会以生产模式编译你的扩展，并将输出写入 dist/<browser>。 对于 monorepo / 子模块项目，关于配置期的环境变量解析（优先项目根，再退回工作区根），请参见 环境变量。

​
什么时候使用 build

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

​
build 命令的能力

能力你得到什么
生产编译为每个目标产出优化过的扩展产物
多目标输出一条命令构建多个浏览器目标
打包支持创建分发用的 zip 产物，可选地附带源代码包
适合 CI 的行为在自动化中保持构建输出与命名可预期

​
用法

extension build [project-path] [options]

​
build 输出

运行 build 后，Extension.js 会为所选浏览器目标生成优化过的文件。输出位于 dist/，每个目标一个子目录。每个目录都包含打包后的 JavaScript、CSS、HTML 和必要的运行时资源。
对于 TypeScript 项目，build 也会重新生成 extension-env.d.ts 环境类型声明（与 dev 写出的是同一个文件）， 所以无论你之前是否运行过 dev，CI 上的 tsc --noEmit 都能保持干净。 纯 JavaScript 项目会跳过这一步。
输出结构示例： 
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

​
浏览器目标矩阵

目标类型示例说明
具名目标chromium、chrome、edge、firefox构建某一个特定的浏览器目标
引擎目标chromium-based、gecko-based、firefox-based适合以引擎家族为单位的工作流
多目标chrome,firefox用逗号分隔的多个目标

​
参数与 flag

flag别名作用默认值
[path]-构建一个本地扩展项目。process.cwd()
--browser <browser>-浏览器 / 引擎目标（chromium、chrome、edge、firefox、引擎别名或逗号分隔的多个值）。chromium
--polyfill [boolean]-为 Chromium 目标启用 browser.* API 兼容 polyfill。false
--zip [boolean]-创建打包好的 zip 产物。false
--zip-source [boolean]-在 zip 输出中包含源代码文件。false
--zip-filename <name>-设置自定义的 zip 文件名。扩展名 + 版本号
--silent [boolean]-抑制构建日志。false
--mode <mode>-覆盖打包器的模式（development、production 或 none）。同时会设置 NODE_ENV。production
--extensions <list>-用逗号分隔的协同扩展或商店 URL。未设置
--install [boolean]-缺失依赖时安装项目依赖。按命令默认行为
--author--author-mode启用维护者诊断信息。关闭

​
共享的全局选项

也支持 全局 flag。

​
模式覆盖

--mode 会覆盖构建的打包器模式以及 NODE_ENV。可选值为 development、production 或 none。当你需要为 staging 或调试产出非生产 bundle 时（类似 Vite / webpack 的工作流），可以用它来对齐行为。 
extension build ./my-extension --mode development
无效的值会以错误退出；默认值仍然是 production。

​
zip 行为

选项作用典型用途
--zip创建打包产物的 zip商店提交 / 手动分发
--zip-filename设置自定义 zip 名称CI 命名规范
--zip-source在产物旁额外加上源代码归档合规 / 审核流水线

​
示例

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

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
在这个示例中，构建以 Edge 与 Chrome 为目标，对输出进行打包，并保存为 my-extension.zip。

​
带 polyfill 支持的构建

extension build ./my-extension --browser=chrome,firefox --polyfill
在这个示例中，构建以 Chrome 与 Firefox 为目标，并在相关地方加入 polyfill 支持。

​
构建源代码与产物 zip

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

​
最佳实践

  • 查看构建日志： 每次构建后检查日志，看是否有警告与缺失资源。
  • 优化你的 manifest： 让 manifest.json 与每个目标浏览器都兼容。
  • 有意识地命名产物： 用 --zip-filename 让 CI 产物命名保持稳定。
  • 逐个目标验证输出： 发布前检查每一个 dist/<browser> 目录。

​
下一步