extension.config.js(或 .mjs / .cjs)，并把设置应用到所有命令与打包器。
工作原理
在项目根目录(通常和package.json 同级) 添加 extension.config.js。
支持的文件名：
extension.config.jsextension.config.mjsextension.config.cjs
类型安全的配置
Extension.js 从extension 包中导出 FileConfig 类型，让编辑器可以对你的配置进行自动补全与类型检查。用 JSDoc 的 @type 标签标注导出即可 —— 它在 extension.config.js、.mjs 与 .cjs 中都能工作，且无需构建步骤：
配置文件的环境加载
extension.config.* 在 Node 中运行，应通过 process.env.* 读取值。
- 在求值
extension.config.*之前，Extension.js 会预加载 env 文件。 - 它会先检查项目目录。
- 在 monorepo 中，如果 Extension.js 在项目本地没找到任何
.env*文件，会回退到最近的 workspace 根目录。workspace 根目录是包含pnpm-workspace.yaml的目录。 - 在配置文件中，优先使用内置的 env 预加载，而不是导入
dotenv。
浏览器配置
每个目标需要不同的浏览器默认值？使用browser：
chrome、edge、firefox、chromium、chromium-based、gecko-based、firefox-based。
常用的浏览器字段：
profile、persistProfilepreferencesbrowserFlags、excludeBrowserFlagschromiumBinary、geckoBinaryextensions(仅加载的附属扩展)
浏览器目标能力
命令配置
用commands 为每个命令定义默认值：
- Extension.js 会把顶层的
extensions与transpilePackages合并到命令默认值中。 - 命令级的值会覆盖顶层的值。
start命令在内部会先运行build，然后preview。Extension.js 会应用commands.start中的设置，包括profile、browserFlags、startingUrl等浏览器启动选项。你也可以把构建相关的设置放进commands.build。
命令通用能力
build 命令能力
dev 命令能力
日志能力
Rspack 配置
需要更高级的打包器自定义？用config 给生成的 Rspack 配置打补丁：
config 也可以是一个对象，Extension.js 会把它合并到生成的配置之上。
完整示例
最佳实践
- 把浏览器特定的值放进
browser：让命令定义专注于工作流，而不是浏览器内部细节。 - 有意识地使用顶层默认值：把共享的
extensions/transpilePackages放在根级，只在必要时覆盖。 - 优先使用
chromiumBinary/geckoBinary这类命名：与当前命令与类型接口一致。 - 保持
config钩子最小化：只添加 Extension.js 一等公民选项未覆盖的内容。