# vite-plugin-pwa 2.0.0 扩大 peer 范围

> vite-plugin-pwa 2.0.0 接受 assets-generator 2.x，要求 Node 20.19.0 或更高版本；生成器自己的 2.0.0 发布记录了它仅支持 ESM 的变化。

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](https://github.com/vite-pwa/vite-plugin-pwa/releases/tag/v2.0.0)）。

2.0.0 标签下的 package 声明需要 Node 20.19.0 或更高版本
（[vite-plugin-pwa 2.0.0 的 package.json](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)）。

另行发布的 assets generator 2.0.0 把破坏性变化描述为「Move to ESM only」
（[assets-generator 2.0.0 release](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)）。

<span id="发布记录包含什么"></span>

## 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](https://github.com/vite-pwa/vite-plugin-pwa/releases/tag/v2.0.0)）。

带标签的 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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/pull/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](https://github.com/vite-pwa/vite-plugin-pwa/pull/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](https://github.com/vite-pwa/vite-plugin-pwa/pull/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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/README.md)、
[vite-plugin-pwa 2.0.0 的 package.json](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.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](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)）。

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](https://github.com/vite-pwa/assets-generator/blob/v2.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](https://github.com/vite-pwa/assets-generator/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)、
[pull request 946](https://github.com/vite-pwa/vite-plugin-pwa/pull/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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)、
[assets-generator 2.0.0 release](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)）。

## 发布包提供的接口

插件的根 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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/README.md)）。

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

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

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

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

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](https://github.com/vite-pwa/assets-generator/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/README.md)）。

带标签的插件 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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.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](https://github.com/vite-pwa/assets-generator/commit/75c0744)）。

<span id="对-pwa-开发者为什么重要"></span>

## 生成器升级对 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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)、
[assets-generator 2.0.0 release](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)）。

peer 范围改动解决的是 pull request 946 点明的条件：显式安装 assets-generator 2.x 时，可以
满足插件发布的 peer 约束。该改动不会替项目选择 2.x；消费方自己的依赖声明与实际解析出的安装
结果，不在 pull request 所展示的两行 peer 范围改动之内
（[vite-plugin-pwa pull request 946](https://github.com/vite-pwa/vite-plugin-pwa/pull/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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)、
[assets-generator 2.0.0 的 package.json](https://github.com/vite-pwa/assets-generator/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)、
[assets-generator 2.0.0 的 package.json](https://github.com/vite-pwa/assets-generator/blob/v2.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](https://github.com/vite-pwa/vite-plugin-pwa/releases/tag/v2.0.0)）。

generator 2.0.0 的 release 把「Move to ESM only」列在破坏性变化下，链接对应的 pull request 和
commit，并提供版本比较；它没有给出迁移步骤
（[assets-generator 2.0.0 release](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)）。

插件 package 在元数据中记录 Node engine 与可选 generator peer 范围。generator release 记录
仅支持 ESM 的破坏性变化，但没有提供迁移步骤
（[vite-plugin-pwa 2.0.0 的 package.json](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)、
[assets-generator 2.0.0 release](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)）。

## 站内相关条目

- [Workbox](/zh/reference/service-worker/workbox/)：Workbox 参考。
- [调试 Service Worker](/zh/reference/service-worker/debugging/)：检查、更新与绕过 Service Worker。
- [Lighthouse](/zh/reference/performance/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](https://github.com/vite-pwa/vite-plugin-pwa/releases/tag/v2.0.0)（github.com）
- [Pull request 946：允许 assets-generator 2.0.0 作为 peer dependency](https://github.com/vite-pwa/vite-plugin-pwa/pull/946)（github.com）
- [Pull request 953：更新破坏性变化说明](https://github.com/vite-pwa/vite-plugin-pwa/pull/953)（github.com）
- [vite-plugin-pwa v2.0.0 的 package.json](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/package.json)（github.com）
- [vite-plugin-pwa v2.0.0 的 README](https://github.com/vite-pwa/vite-plugin-pwa/blob/v2.0.0/README.md)（github.com）
- [assets-generator v2.0.0](https://github.com/vite-pwa/assets-generator/releases/tag/v2.0.0)（github.com）
- [assets-generator ESM commit](https://github.com/vite-pwa/assets-generator/commit/75c0744)（github.com）
- [assets-generator v2.0.0 的 package.json](https://github.com/vite-pwa/assets-generator/blob/v2.0.0/package.json)（github.com）