升级、FAQ 与社区资源
本教程共 45 篇 · 第 45 篇 · 更新于 2026-08-13 · 约 5 分钟阅读
本节目标：讲透「怎么跟上 WXT 的版本节奏」这件事。0.x 阶段迭代快，学会看升级指南比背每个版本的改动更值钱；再精选几条高频 FAQ 和社区资源，作为全书的收尾。
先懂 0.x 的版本节奏
WXT 还没到 1.0，版本号是 0.MINOR.PATCH。这条线上有个重要约定：第二位数字（MINOR）的变动视为 major 版本，可能带破坏性变更。也就是说 0.20 → 0.21 和别的项目的 2.0 → 3.0 是一个量级，升级前必须看升级指南。等 1.0 发布后，只有主版本号变化才有破坏性变更。
升级心态上别慌：官方升级指南把所有破坏性变更按版本段整理好了，每段开头还有「先通读一遍再动手」的提示。按流程走，升级是半小时到几小时的活儿，不是冒险。
升级方法论：四步走
大版本升级的标准流程：
1. 安装，先跳过脚本（prepare 在大版本切换后大概率报错，稍后再跑）
pnpm i wxt@latest --ignore-scripts
2. 对照升级指南修掉破坏性变更
3. 重新生成类型
pnpm wxt prepare
4. 手动验证 dev 模式与生产构建都正常小版本（patch）没有特殊步骤，直接 pnpm i wxt@latest 完事。
Tip升级指南不用逐版背。正确用法：升级前通读当前版本的变更段，改完代码跑
wxt prepare看类型报错，再对照报错回到指南里找对应条目。
0.20 → 0.21 关键变化示例
这一版的主题是「瘦身与简化配置」，挑几条影响面大的讲：
- 安装体积：v0.20 装完是 98MB / 366 个包，v0.21 降到 22MB / 156 个包，约为原来的 22%。
- 环境要求：Node.js 提到 >=22，Vite 需要 ^6.3.4 及以上（Vite 5 不再支持），TypeScript >=5.4。
- 依赖变成 peerDependencies：
vite、web-ext、typescript不再由 WXT 自带，vite必须自己加进 devDependencies。web-ext变成可选项——装上它，dev 模式才会自动开浏览器；不装，这个功能就关闭（新项目默认装）。 .wxt/tsconfig.json选项更新：跟随 Vite 推荐配置，新增verbatimModuleSyntax、noUncheckedIndexedAccess等严格选项。升级后如果报错，这两个最可疑，建议修掉而不是回退（回退方法指南里有，用prepare:tsconfig钩子，§30 讲过钩子）。url:导入移除：import 'url:https://...'这种从 URL 打包远程代码的写法因供应链风险被移除，改用 npm 包或把文件下载到本地。- zip 命名模板变化：
{{version}}现在只解析manifest.version，新增{{versionName}}、{{packageVersion}}、{{modeSuffix}}三个变量；自定义过模板的话要对照调整（§38）。 - sources zip 的包含规则修正：
includeSources/excludeSources改为标准 allowlist 语义（原来all - exclude + include，现在include - exclude），另加zip.dotSources开关控制隐藏文件。官方提示这是升级中最可能踩的坑，好在wxt zip -b firefox现在会打印源码包内每个文件，调试方便。 - 内容脚本 UI 的 DOM 简化：
createShadowRootUi内部从完整<html>结构简化为<style>+<div>，多数项目无需改动；样式坏了可临时装@webext-core/isolated-element@^1过渡（§15 相关）。 globalName默认 false：内容脚本/未列出脚本默认不再生成全局变量，靠executeScript读返回值的记得显式开（§13）。- Chrome 商店 CWS v2 API：
wxt submit支持 v2 API（服务账号认证，密钥不过期），v1 将于 2026 年 10 月 15 日停用，尽早用wxt submit init迁移（§39）。
FAQ 精选
官方 FAQ 挑几条最常被问的：
内容脚本为什么不在 manifest 里？ 开发模式下 WXT 动态注册内容脚本，这样改文件能单独热更新而不用重载整个扩展。想在开发时查看已注册脚本，打开 service worker 控制台执行：
await chrome.scripting.getRegisteredContentScripts();怎么不让 dev 自动开浏览器？ 不装 web-ext 依赖即可；装了的话按 §05 的办法在 web-ext 配置里设 disabled: true。
组件库在内容脚本里不工作？ 十有八九是样式或 Teleport/Portal 渲染到了 ShadowRoot 外面，被隔离挡掉了。解法是告诉组件库把样式和挂载目标放进 ShadowRoot 内（Ant Design 用 StyleProvider，Mantine 用 getRootElement，§15 有完整讨论）。
内容脚本 UI 在个别网站大小不对？ 通常是 rem 单位被网页根字号带偏。用 postcss-rem-to-responsive-pixel 在构建时把 rem 转成 px 即可。
Docker/devcontainer 里怎么跑 dev？ 项目目录挂载到宿主机、关掉自动开浏览器、用 wxt --host 0.0.0.0 监听所有网卡，文件监听不生效时开 watchOptions.usePolling。
文档能喂给 AI 吗？ 能。WXT 提供 llms.txt 风格的 Markdown 文档，还有汇总好的知识文件 https://wxt.dev/knowledge/index.json，官网右下角也有「Ask AI」入口（knowledge.wxt.dev）。
社区资源
- 官方渠道：GitHub Discussions 提问（wxt-dev/wxt）、Discord 实时交流。
- 博客：Aabid 的《Building Modern Cross Browser Web Extensions》系列（aabidk.dev，含 Shadow DOM 与 Portal 实战）；rxliuli 的《Building Browser Extensions with WXT》系列（rxliuli.com，中文）。
- NPM 包：
@webext-core/*（消息、存储等跨浏览器工具集，§17/§18 的主角）、Comctx（跨上下文类型安全 RPC）、wxt-local-analytics（§34 analytics 的本地数据提供方）。
全书收尾
到这里，四十五章走完了：从「扩展是什么」到「怎么上架」，从命令行到迁移升级。记住两条主线：约定优于配置，目录和入口文件就是框架的语言；类型安全贯穿始终，browser、#imports、wxt/storage 都在帮你把错误挡在编译期。剩下的事，交给 npx wxt dev 和你的浏览器。
小结
- 0.x 阶段迭代快：学会看升级指南，比背版本改动更值钱。
- FAQ 里的高频问题（自动开浏览器、内容脚本样式、rem、Docker）都有现成解法。
- 两条主线贯穿全书：约定优于配置，类型安全贯穿始终。