vite-plugin-pwa 2.0.0 扩大 peer 范围

vite-plugin-pwa 2.0.0 于 2026 年 10 月 3 日发布，是一次大版本更新。可选的对等依赖（peer dependency）范围扩大后，@vite-pwa/assets-generator 2.x 也能满足插件的依赖要求。README 同时更新了破坏性变化说明，记录这次大版本的变动 （vite-plugin-pwa 2.0.0 release）。

2.0.0 标签下的 package 声明需要 Node 20.19.0 或更高版本 （vite-plugin-pwa 2.0.0 的 package.json）。

另行发布的 assets generator 2.0.0 把破坏性变化描述为「Move to ESM only」 （assets-generator 2.0.0 release）。

2.0.0 的发布改动

发布页把 2.0.0 称为下一个大版本，并将条目分在 enhancement、documentation 与 chore 标题下。 enhancement 是允许 @vite-pwa/assets-generator ^2.0.0 作为 peer dependency；documentation 条目把 README 的破坏性变化说明更新为 2.0.0；chore 条目则更换发布工作流、固定工作流 action， 并更新示例所用的 assets generator （vite-plugin-pwa 2.0.0 release）。

带标签的 package 文件精确给出了依赖范围。其 peerDependencies 接受 @vite-pwa/assets-generator ^1.0.0 || ^2.0.0；同一文件还在 peerDependenciesMeta 中把它 标为 optional: true。因此，插件的 peer 约束接受 generator 2.x，但这项元数据没有把 assets generator 变成必须安装的 peer （vite-plugin-pwa 2.0.0 的 package.json）。

该 package 中的 Vite peer 范围仍是从 ^3.1.0 到 ^8.0.0 的并集。Workbox peer dependency 是 workbox-build 与 workbox-window，两者均为 ^7.4.1 （vite-plugin-pwa 2.0.0 的 package.json）。

大版本背后的改动

Pull request 946 改了两行 package 元数据，并加入一条 README 说明。它把 Node engine 从 >=16.0.0 改为 >=20.19.0，把 assets generator 的 peer 范围从 ^1.0.0 改为 ^1.0.0 || ^2.0.0，并记录新的 Node 下限。该 pull request 于 2026 年 9 月 30 日创建并合并 （vite-plugin-pwa pull request 946）。

作者对依赖问题的描述很具体：同时安装 vite-plugin-pwa 与 assets generator 的项目此前会被约 束在 generator ^1.0.0，除非通过 npm override 特别安装 2.0.0；这项改动把 2.0.0 加入合法 peer dependency。该陈述只涉及显式安装的 2.x 是否满足 peer 范围，并没有说插件会改写消费项 目的依赖声明或 lockfile （vite-plugin-pwa pull request 946）。

Pull request 953 提供了发布页所列的文档修正。其描述说，发布工具对 semantic pull request 的 处理使 pull request 946 触发大版本，因此 README 应把先前写成小版本的说明改为 2.0.0。它在 2026 年 10 月 3 日创建并合并，时间早于 2.0.0 发布 （vite-plugin-pwa pull request 953）。

2.0.0 标签下的 README 写明，从 2.0.0 起，vite-plugin-pwa 需要 Node 20.19.0 或更高版本。这 一数值也记录在标签下 package 的 engines.node 字段中；同一 package 另行把 assets generator 列为可选 peer （vite-plugin-pwa 2.0.0 README、 vite-plugin-pwa 2.0.0 的 package.json）。

assets-generator 的版本边界

assets-generator 项目在 2026 年 9 月 12 日发布了自己的 2.0.0。它的 release notes 只有一项破 坏性变化陈述：「Move to ESM only」。页面把这条说明链接到 pull request 70（「feat!: move to ESM only」）与对应 commit，并给出从 generator 1.0.4 到 2.0.0 的比较；release notes 没有规定消费方必须采用哪一种迁移步骤 （assets-generator 2.0.0 release）。

generator 标签下的 package 元数据声明版本 2.0.0，把 type 设为 module，并要求 Node 20.19.0 或更高版本。它把根 export 映射到 ./dist/index.mjs，把 types 映射到 dist/index.d.mts （assets-generator 2.0.0 的 package.json）。

同一份 export map 把 ./config、./presets、./api 与记录的 generator API 子路径指向 .mjs 文件；typesVersions 把这些子路径指向 .d.mts 文件；pwa-assets-generator binary 则指向 ./bin/pwa-assets-generator.mjs。这些都是标签下 package 元数据直接记录的模块与类型路径 （assets-generator 2.0.0 的 package.json）。

vite-plugin-pwa 2.0.0 没有用 generator 2.x 替换 1.x 支持。peer 范围的并集保留 ^1.0.0， 并加入 ^2.0.0。因此，声明 generator 1.x 的项目仍在发布的 peer 范围内；选择兼容 2.x 声明 的项目，则不再需要 pull request 946 所说的 override 来满足这一项 peer 约束 （vite-plugin-pwa 2.0.0 的 package.json、 pull request 946）。

插件 package 在 peerDependenciesMeta 中为 generator 记录 optional: true，并在 peerDependencies 中声明 ^1.0.0 || ^2.0.0。generator 自己的 release 则把「Move to ESM only」列在破坏性变化下 （vite-plugin-pwa 2.0.0 的 package.json、 assets-generator 2.0.0 release）。

发布包提供的接口

插件的根 export 为 import 与 require 保留不同的模块路径。import 分支使用 ./dist/index.js 与 ./dist/index.d.ts，require 分支使用 ./dist/index.cjs 与 ./dist/index.d.cts。顶层 module、main 和 types 字段分别指向对应文件；发布文件列表则 包括顶层声明文件、dist 和 types （vite-plugin-pwa 2.0.0 的 package.json）。

同一份 export map 为 preact、react、solid、svelte、vanillajs 与 vue 发布只含类型 声明的子路径，也为 client、info 与 pwa-assets 指定类型声明。它还开放 package 元数据与 通配子路径。这些入口属于 vite-plugin-pwa 本身，与可选的 assets-generator peer 分开记录 （vite-plugin-pwa 2.0.0 的 package.json）。

标签下的 README 把插件描述为不绑定框架，并列出对 Vanilla JavaScript、Vue 3、React、Svelte、 SolidJS 与 Preact 的内置支持。README 还列出 SvelteKit、VitePress、Astro、Nuxt 3、Remix 等 元框架集成（vite-plugin-pwa 2.0.0 README）。

README 还说，插件为常见用例提供合理的内置默认配置，同时开放完整的行为定制能力；插件使用 TypeScript 编写，并且可以完整进行 tree shaking。README 在功能摘要中逐项列出了这些陈述 （vite-plugin-pwa 2.0.0 README）。

对于 PWA 输出，README 写明插件可以通过 Workbox 生成具备离线支持的 service worker、注入 Web app manifest、为离线支持配置静态资源，并在出现新内容时自动重新加载。它还单列开发支持，用于 在开发期间调试自定义 service worker 逻辑 （vite-plugin-pwa 2.0.0 README）。

README 把 PWA Assets Generator 的能力描述为通过一条命令和一张源图片生成 PWA 资源，同时把 PWA Assets Integration 描述为在应用中提供、生成并注入 PWA 资源。这些是 README 明列的能力， 而标签下的 package 元数据另行把 generator 记录为可选 peer （vite-plugin-pwa 2.0.0 README、 vite-plugin-pwa 2.0.0 的 package.json）。

README 的用法章节先把 vite-plugin-pwa 安装为开发依赖，再在 Vite 配置中导入 VitePWA，并把 VitePWA() 放进 plugins 数组。对于完整配置，README 指向项目文档与 TypeScript 类型声明 （vite-plugin-pwa 2.0.0 README）。

generator package 发布配置与预设入口，其中包括 minimal 和 minimal-2023。它的 API 子路径 覆盖 instructions、HTML markup、manifest icons entry 与 assets generation。各 JavaScript export 指向 .mjs 文件，对应类型映射指向 .d.mts；命令行入口名为 pwa-assets-generator （assets-generator 2.0.0 的 package.json）。

2.0.0 标签下的 README 在新的 Node 要求旁保留了早期安装边界：从 0.17 起要求 Vite 5，从 0.16 起因 Workbox 7 的要求而需要 Node 16，从 0.13 起要求 Vite 3.1 或更高版本；新增说明则写明从 2.0.0 起需要 Node 20.19.0 或更高版本。其配置章节把插件的 TypeScript 声明链接为完整配置参考， 并分别链接 Web app manifest 与 Workbox 的文档 （vite-plugin-pwa 2.0.0 README）。

带标签的插件 package 把 sideEffects 设为 false，并采用 MIT 许可证。运行时依赖列表包含 debug、pretty-bytes、tinyglobby、workbox-build 与 workbox-window；其中两个 Workbox package 也以 ^7.4.1 出现在 peer dependency 列表中。发布配置指定公开访问并启用 provenance （vite-plugin-pwa 2.0.0 的 package.json）。

generator release 所链接的 commit 把根入口、配置、预设与 API export 从同时提供 import 和 require 目标改为只指向 .mjs 文件，删除 package 的 main 与 module 字段，并把顶层类型声明 从 dist/index.d.ts 改为 dist/index.d.mts。该 commit 还把 engines.node 从 >=16.14.0 提高到 >=20.19.0，以 tsdown 取代原有的 unbuild 命令，并新增 TypeScript 类型检查脚本 （assets-generator ESM commit）。

生成器升级对 Node 依赖的影响

vite-plugin-pwa 2.0.0 在 engines 中声明 node: ">=20.19.0"，接受 assets-generator ^1.0.0 || ^2.0.0 作为 peer，并把该 peer 标为可选。assets-generator 2.0.0 release 另行把 「Move to ESM only」记录为破坏性变化 （vite-plugin-pwa 2.0.0 的 package.json、 assets-generator 2.0.0 release）。

peer 范围改动解决的是 pull request 946 点明的条件：显式安装 assets-generator 2.x 时，可以 满足插件发布的 peer 约束。该改动不会替项目选择 2.x；消费方自己的依赖声明与实际解析出的安装 结果，不在 pull request 所展示的两行 peer 范围改动之内 （vite-plugin-pwa pull request 946）。

带标签的插件元数据为 generator peer 记录 optional: true 与 ^1.0.0 || ^2.0.0 范围。带 标签的 generator 元数据则记录 type: "module"，以及它自己的 node: ">=20.19.0" engine 字段（vite-plugin-pwa 2.0.0 的 package.json、 assets-generator 2.0.0 的 package.json）。

两个标签下的文件还记录了不同的根 export 条目。插件把 import 的 default 映射到 ./dist/index.js，把 require 的 default 映射到 ./dist/index.cjs，并分别发布 dist/index.d.ts 与 dist/index.d.cts。generator 则把根 export 映射到 ./dist/index.mjs，把 types 映射到 dist/index.d.mts。在插件的 export map 之外，main 指向 dist/index.cjs，module 指向 dist/index.js，types 指向 dist/index.d.ts；generator 的 files 数组则记录 bin 与 dist （vite-plugin-pwa 2.0.0 的 package.json、 assets-generator 2.0.0 的 package.json）。

release 页面列出一项 Enhancement、一项 Documentation 与三项 Chore。Enhancement 是允许 generator ^2.0.0；Documentation 是更新 README 中的大版本说明；Chore 涉及发布工作流、固定 workflow actions，以及更新示例中的 generator （vite-plugin-pwa 2.0.0 release）。

generator 2.0.0 的 release 把「Move to ESM only」列在破坏性变化下，链接对应的 pull request 和 commit，并提供版本比较；它没有给出迁移步骤 （assets-generator 2.0.0 release）。

插件 package 在元数据中记录 Node engine 与可选 generator peer 范围。generator release 记录 仅支持 ESM 的破坏性变化，但没有提供迁移步骤 （vite-plugin-pwa 2.0.0 的 package.json、 assets-generator 2.0.0 release）。

站内相关条目

• Workbox：Workbox 参考。
• 调试 Service Worker：检查、更新与绕过 Service Worker。
• Lighthouse：Lighthouse 参考。

待核实

• release notes 没有列出项目从 assets-generator 1.x 转向 2.x 的迁移步骤。
• 某个具体项目能否采用 Node 20.19.0 或更高版本，无法由 package 发布材料确定。
• 如果没有消费项目的 manifest 与 lockfile，无法确认特定 package manager 会怎样解析可选 peer。
• 所引来源无法确认某个具体配置是否通过 CommonJS 加载 assets-generator。
• 2.0.0 release 没有以兼容性矩阵记录 peer 范围内每个 Vite 与 Workbox 版本组合的运行行为。

参考来源

• vite-plugin-pwa v2.0.0（github.com）
• Pull request 946：允许 assets-generator 2.0.0 作为 peer dependency（github.com）
• Pull request 953：更新破坏性变化说明（github.com）
• vite-plugin-pwa v2.0.0 的 package.json（github.com）
• vite-plugin-pwa v2.0.0 的 README（github.com）
• assets-generator v2.0.0（github.com）
• assets-generator ESM commit（github.com）
• assets-generator v2.0.0 的 package.json（github.com）