Vite PWA 插件开发模式详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00381/article/details/148575454

Vite PWA 插件开发模式详解

vite-plugin-pwa 项目地址: https://gitcode.com/gh_mirrors/vit/vite-plugin-pwa

前言

在现代 Web 应用开发中，渐进式 Web 应用(PWA)已经成为提升用户体验的重要手段。vite-plugin-pwa 作为 Vite 生态中的 PWA 解决方案，提供了强大的功能支持。本文将重点介绍该插件在开发环境中的使用方法和注意事项。

开发模式概述

从 v0.11.13 版本开始，vite-plugin-pwa 支持在开发环境中使用 Service Worker。这种设计允许开发者在开发阶段就能测试 PWA 相关功能，而无需每次都进行生产构建。

需要注意的是，开发模式下：

不会注册完整的 PWA，仅启用 Service Worker 逻辑
只在必要时会注册 Service Worker 预缓存清单中的 navigateFallback
需要显式启用开发模式配置

基础配置

要启用开发模式下的 Service Worker，需要在插件配置中添加 devOptions：

import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    VitePWA({
      devOptions: {
        enabled: true  // 启用开发模式
      }
    })
  ]
})

配置选项详解

devOptions 提供了多个配置项，下面详细介绍每个选项的作用：

1. enabled

是否在开发环境中启用 Service Worker，默认为 false。

2. type

Service Worker 类型，可选值为：

'classic'：传统 Service Worker（默认值）
'module'：模块化 Service Worker（仅 Chromium 内核浏览器支持）

3. disableRuntimeConfig

是否禁用运行时配置（仅对 generateSW 策略有效）。

4. navigateFallback

配置回退 URL（仅对 injectManifest 策略有效）。

5. navigateFallbackAllowlist

配置允许回退的 URL 正则表达式列表（从 v0.12.4 开始替代 webManifestUrl）。

开发模式下的特殊行为

1. manifest.webmanifest 服务

从 v0.12.1 开始，开发模式下也会提供 manifest.webmanifest 文件，可以在开发者工具中检查。

2. 策略差异

generateSW 策略

忽略 devOptions.navigateFallback
强制使用 type: 'classic' 注册以避免客户端错误
默认只拦截根路径 /，可通过 navigateFallbackAllowlist 调整

injectManifest 策略

支持使用 type: 'module'（仅限开发模式）
生产构建仍使用 'classic' 以保证兼容性
需要显式配置 navigateFallback
不支持 HMR（热模块替换）

最佳实践

1. 路由拦截控制

建议只拦截应用入口点，避免影响其他路由的正常工作：

let allowlist: undefined | RegExp[]
if (import.meta.env.DEV)
  allowlist = [/^\/$/]

registerRoute(new NavigationRoute(
  createHandlerBoundToURL('index.html'),
  { allowlist }
))

2. 自定义注册逻辑

如果手动注册 Service Worker，需要区分开发和生产环境：

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register(
    import.meta.env.MODE === 'production' ? '/sw.js' : '/dev-sw.js?dev-sw',
    { 
      type: import.meta.env.MODE === 'production' ? 'classic' : 'module',
      scope: '/' // 根据需要配置作用域
    }
  )
}