打包：构建产物与 zip
本教程共 45 篇 · 第 38 篇 · 更新于 2026-08-13 · 约 4 分钟阅读
本节目标：理解 .output 目录结构，掌握 wxt build 与 wxt zip 的用法和参数，学会配置源码包（includeSources / excludeSources），并掌握发布前的产物检查方法。
build 与 zip：一个生成目录，一个生成压缩包
- wxt build：生产构建，生成可加载的展开目录；
- wxt zip：先构建，再把产物压缩成商店上传用的 zip。
两个命令的产物都在 .output/ 下，按浏览器和 manifest 版本分目录：.output/chrome-mv3/、.output/firefox-mv2/。zip 文件也在 .output/ 下，命名类似 {名称}-{版本}-chrome.zip。日常命令的分工如 §05 所述，完整参数见 §41。
wxt build 的常用参数
wxt build [root]常用选项：
| 选项 | 作用 |
|---|---|
| -b, —browser | 指定浏览器：chrome / firefox / edge / safari / opera |
| -e, —filter-entrypoint | 只构建指定入口点，适合调试单个功能 |
| —mv3 / —mv2 | 指定 manifest 版本 |
| —analyze / —analyze-open | 可视化产物体积，—analyze-open 自动打开 stats.html |
| -c, —config | 使用指定配置文件 |
| -m, —mode | 设置环境模式 |
| —debug / —level | 调试模式与日志级别 |
wxt zip：打包与源码包
wxt zip 默认只在目标浏览器是 Firefox 时额外生成源码包（sources zip，Firefox 商店审核需要）。
Firefox 为什么强制要源码包？AMO（Firefox 附加组件商店）要求上传源码 zip，用来重建扩展、以可读形式审核代码。WXT 打包源码时会自动排除一批文件：配置文件、隐藏文件、测试、被排除的入口点。但自动排除不保证完美，上传前必须手动检查 zip 内容。
用 wxt.config.ts 的 zip 字段自定义打包行为：
// wxt.config.ts
export default defineConfig({
zip: {
sources: true, // true 始终打源码包；false 从不；默认 Firefox 才打
includeSources: ['.env'], // 白名单：需要进源码包的文件
excludeSources: ['docs', 'scripts'], // 黑名单：从白名单里剔除
},
});includeSources/excludeSources 从 v0.21 起是标准白名单语义：
。不再有「默认全进 + 追加」的旧行为——需要进包的基础文件和目录要显式写进 includeSources，再从里面剔除 excludeSources；隐藏文件默认不进包，要开
zip.dotSources（§45 会讲）。另外别被老教程绕晕：ignoredSources早在 v0.15 就改名为excludeSources，不是 0.21 才改的。
两个常见坑：
- .env 会影响产物 chunk 的 hash。打包时删掉 .env、审核方重建时却带着它，构建结果会不一致。要么把 .env 加进 includeSources，要么打包前删掉——里面别放密钥（issue #377）；
- 依赖了私有 npm 包，又不想把 registry 认证 token 交给审核方，用 zip.downloadPackages 把私有包下载进源码包，package.json 会被改写为 overrides / resolutions 指向本地文件。注意 WXT 用 npm pack 下载，需要配置好 .npmrc。
验证源码包能重建
第一次提交 Firefox，或改过项目结构，一定要验证：把源码 zip 解压出来，按 README（或 SOURCE_CODE_REVIEW.md）里的命令重建：
pnpm install
pnpm zip:firefox重建产物必须和主项目里 wxt build -b firefox 的输出一致。README 里写上这两条命令，审核方才能照做。
发布前检查产物，而不是猜
构建完成后按三步走：
- 打开生成目录的 manifest.json，逐项核对：manifest_version、background、permissions 与 host_permissions、内容脚本、侧边栏声明、browser-specific settings（如 §35 所述）、_locales、图标与页面路径；
- 解压最终 zip 再检查一遍，防止把旧产物传上商店；
- 对照源配置检查：内容脚本 matches 与产品承诺一致、环境变量指向生产环境、没有测试 URL 与调试日志。
mkext 项目的发布前裁剪清单还提醒：产品名、说明、Logo、图标要替换；不需要的弹窗、newtab、DevTools 入口要删掉；manifest key 与扩展 ID 属于你自己的产品；隐私政策和商店数据披露要和实际代码一致。
版本号管理
提交商店前更新 package.json 的 version，并确认生成 manifest 用的是预期版本。商店会拒绝重复版本号。建议代码 tag、zip 文件名、商店版本三者可追溯。
完整发布检查顺序：lint → typecheck → 单元测试 → build，再把展开目录分别加载到 Chrome 和 Firefox 人工验证（如 §36、§37 所述）。
小结
wxt build生成展开目录，wxt zip打包，.output/{浏览器}-{mv}/是产物根。- 0.21 起源码包是白名单语义：
includeSources − excludeSources，隐藏文件要开zip.dotSources。 - 发布前检查产物而不是猜：manifest、权限、图标、双浏览器对比。