Vue CLI PWA 插件实战指南：@vue/cli-plugin-pwa 的 Service Worker 与 Web App Manifest 配置详解

Vue CLI PWA 插件实战指南vue/cli-plugin-pwa 的 Service Worker 与 Web App Manifest 配置详解【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli导读本文以 Vue CLI 官方仓库中的 PWA 核心插件vue/cli-plugin-pwa为对象系统讲解如何在 Vue 项目中一键接入渐进式 Web 应用PWA能力。你将掌握该插件在生产构建中自动生成 Service Worker基于 Workbox、在开发模式下用 no-op 脚本清理旧缓存的工作机制以及vue.config.js中pwa字段全部配置项的取值、默认值与底层实现最终能独立配置出可安装、可离线运行、带完整图标体系的 PWA 应用。插件概览一个命令让 Vue 应用具备 PWA 能力vue/cli-plugin-pwa是 Vue CLI 官方插件体系中负责 PWA 能力的核心模块源码位于 packages/vue/cli-plugin-pwa版本 5.0.9。它基于workbox-webpack-plugin依赖版本^6.1.0见 package.json实现 Service Worker 的生成同时借助html-webpack-plugin的钩子在构建产物 HTML 的head中注入 Web App Manifest、各类图标与移动端 meta 标签让应用可以被添加到主屏、支持离线访问。插件的工作可划分为三条主线分别对应仓库中的三份关键源码生产环境的 Service Worker 生成——由 index.js 在NODE_ENV production时向 webpack 配置注入workbox插件HTML 头部标签与 manifest.json 注入——由 lib/HtmlPwaPlugin.js 实现它挂在 html-webpack-plugin 的alterAssetTagGroups钩子上开发模式的缓存清理——由 lib/noopServiceWorkerMiddleware.js 提供 dev server 中间件。Service Worker 只在生产环境启用为什么插件注册的 Service Worker仅在NODE_ENV production时生效即只有执行npm run build或yarn build之后才真正写入service-worker.js。官方文档明确给出了理由如果在开发模式启用 Service Worker浏览器可能直接使用先前缓存过的旧资源导致本地最新改动无法生效造成改了代码看不到效果的假象。开发模式下插件改为向 dev server 注入一个名为noopServiceWorkerMiddleware的中间件见 index.js 与 lib/noopServiceWorkerMiddleware.js。当请求路径为/service-worker.js时它直接返回 lib/noopServiceWorker.js 的内容。这份 no-op 脚本的作用是重置同一 host:port 下先前注册的任何 Service Worker// lib/noopServiceWorker.js节选 self.addEventListener(install, () self.skipWaiting()) self.addEventListener(fetch, () {}) self.addEventListener(activate, () { self.clients.matchAll({ type: window }).then(windowClients { for (const windowClient of windowClients) { // 强制已打开的页面刷新使其从本地 dev server 拿到最新响应 windowClient.navigate(windowClient.url) } }) })它通过skipWaiting()跳过等待阶段、通过空fetch监听放弃对请求的拦截并在activate阶段强制刷新所有已打开的窗口页面。这正是为了应对开发版与生产版在同一个 host:port 上交替访问生产 Service Worker 劫持开发请求的场景。注意如果承载生产应用的服务对/service-worker.js设置了很长的缓存头这个 no-op 脚本可能无法立即生效此时需要在浏览器 DevTools → Application → Service Workers 中手动注销 Service Worker。本地测试 Service Worker 的正确姿势先执行npm run build完成构建再从构建输出目录dist起一个简单的 HTTP 服务器如npx serve dist并推荐使用浏览器无痕窗口访问以避免浏览器缓存带来的干扰。配置文件与优先级vue.config.js 中的 pwa 字段所有 PWA 配置都通过vue.config.js中的pwa属性或package.json的vue字段传入。插件入口首先读取该配置并处理public/manifest.json的优先级问题见 index.js若项目public/目录下存在manifest.json且用户未在vue.config.js中显式配置pwa.manifestOptions则自动加载该文件内容作为 manifest 数据若两者同时存在插件会打印警告public/manifest.json将被忽略以pwa.manifestOptions为准。也就是说manifest 数据有三层来源按优先级从低到高为插件内置默认值 →public/manifest.json→vue.config.js中的pwa.manifestOptions。pwa 配置项全解字段、默认值与底层行为以下配置项均在vue.config.js的pwa对象下生效。它们的默认值定义在 lib/HtmlPwaPlugin.js 的defaults常量中与官方文档完全一致。pwa.workboxPluginMode选择 Workbox 的两种工作模式默认值GenerateSW可选值GenerateSW或InjectManifest对应底层workbox-webpack-plugin的两个插件类。两种模式的行为差异模式行为适用场景GenerateSW默认每次重新构建时由插件自动生成一份全新的 Service Worker 文件绝大多数标准项目自动收集构建产物的文件清单生成预缓存清单并内置运行时缓存策略InjectManifest以你提供的一个既有 Service Worker 文件swSrc为起点将预缓存清单注入该文件的副本需要完全掌控 Service Worker 逻辑如自定义推送、自定义缓存策略的高级场景从源码 index.js 可以看到插件从workbox-webpack-plugin模块中按模式名取用对应插件类如果传入的模式不在支持列表内会直接抛出错误if (!(workboxPluginMode in workboxWebpackModule)) { throw new Error( ${workboxPluginMode} is not a supported Workbox webpack plugin mode. Valid modes are: ${Object.keys(workboxWebpackModule).join(, )} ) }pwa.workboxOptions透传给 Workbox 的原始配置该对象会被直接透传给workbox-webpack-plugin。在GenerateSW模式下可配置缓存策略、globPatterns、maximumFileSizeToCacheInBytes等在InjectManifest模式下则至少需要提供swSrc你的自定义 Service Worker 入口文件路径。值得关注的是插件在合并配置时index.js会先注入一组默认排除规则这些文件不会被写入预缓存清单const defaultOptions { exclude: [ /\.map$/, /img\/icons\//, /favicon\.ico$/, /^manifest.*\.js?$/ ] }即source map、img/icons/目录下的图标、favicon.ico以及 manifest 相关文件都不参与预缓存。另外GenerateSW模式还会额外注入cacheId: name取自package.json的name字段用于在 Cache Storage 中区分不同应用的缓存这些默认值均可被你传入的workboxOptions覆盖。pwa.name应用名称与 iOS 标题默认值package.json中的name字段作用作为生成 HTML 中apple-mobile-web-app-titlemeta 标签的值。注意文档提醒若要修改它需要同步编辑public/manifest.json保持两者一致。pwa.themeColor主题色默认值#4DBA87Vue 品牌绿作用生成meta nametheme-color标签同时用于mask-icon图标的color属性并作为生成 manifest 时theme_color字段的来源。pwa.msTileColorWindows 磁贴颜色默认值#000000作用生成meta namemsapplication-TileColor配合msapplication-TileImage让应用在 Windows 磁贴上拥有正确外观。pwa.appleMobileWebAppCapableiOS 全屏能力开关默认值no作用生成meta nameapple-mobile-web-app-capable。默认no是因为 iOS 11.3 之前对 PWA 支持不完善盲目开启该 meta 标签可能导致 iOS Safari 行为异常。pwa.appleMobileWebAppStatusBarStyleiOS 状态栏样式默认值default作用生成meta nameapple-mobile-web-app-status-bar-style可选值通常为default、black、black-translucent。pwa.assetsVersion静态资源缓存破版本号默认值作用当需要对抗浏览器对图标和 manifest 的缓存时给图标与 manifest 的 URL 追加?vpwa.assetsVersion查询参数。实现见 HtmlPwaPlugin.js 的assetsVersionStr assetsVersion ??v${assetsVersion}: 。pwa.manifestPathWeb App Manifest 路径默认值manifest.json作用应用 manifest 的路径。若该值是一个绝对 URL如 CDN 地址源码通过/(http(s?)):\/\//正则判断插件在构建时不会在 dist 目录生成manifest.json而只输出指向该 URL 的link relmanifest标签否则会在构建产物中生成该文件见 HtmlPwaPlugin.js 的isHrefAbsoluteUrl判断分支。pwa.manifestOptions覆盖 manifest.json 内容默认值{}作用该对象用于生成manifest.json。若以下属性未在对象中定义则回退到pwa配置项或插件默认值manifest 字段取值来源namepwa.nameshort_namepwa.namestart_url.displaystandalonetheme_colorpwa.themeColor从源码 HtmlPwaPlugin.js 可以看到插件内置了一份defaultManifest除上述字段外还包含默认图标组android-chrome-192x192.png、android-chrome-512x512.png及对应的 maskable 版本与background_color: #000000。最终的 manifest 合并顺序为Object.assign(publicOptions, defaultManifest, manifestOptions) // publicOptions { name, short_name, theme_color }来自 pwa 配置即你的manifestOptions拥有最高优先级会覆盖内置默认值。pwa.manifestCrossoriginmanifest 链接的跨域属性默认值undefined即不输出crossorigin属性作用为生成的 manifestlink标签设置crossorigin属性。当你的 PWA 部署在需要认证的反向代理之后时可能需要设置。从 ui.js 的配置界面可以看到可取值为nonenull、anonymous、use-credentials。pwa.iconPaths自定义图标路径默认值{ faviconSVG: img/icons/favicon.svg, favicon32: img/icons/favicon-32x32.png, favicon16: img/icons/favicon-16x16.png, appleTouchIcon: img/icons/apple-touch-icon-152x152.png, maskIcon: img/icons/safari-pinned-tab.svg, msTileImage: img/icons/msapplication-icon-144x144.png }作用替换各平台使用的图标路径。自 v4.3.0 起将任一值设为null即可跳过对应图标的注入。这些路径相对于public目录生成器默认提供完整的图标组见 generator/template/public/img/icons。在 HtmlPwaPlugin.js 中每个非null的图标都会生成对应的link或meta标签配置项生成的标签faviconSVGlink relicon typeimage/svgxmlfavicon32/favicon16link relicon typeimage/png sizes32x32/16x16appleTouchIconlink relapple-touch-iconiOS 添加到主屏maskIconlink relmask-icon colorthemeColorSafari 固定标签页msTileImagemeta namemsapplication-TileImageWindows 磁贴另外注意 HtmlPwaPlugin.js 中一个细节插件会用 IE 条件注释包裹原有 favicon即!--[if IE]...![endif]--避免旧版 IE 对 SVG favicon 的兼容问题。完整示例配置官方文档给出的可运行示例放入vue.config.jsmodule.exports { // ...other vue-cli plugin options... pwa: { name: My App, themeColor: #4DBA87, msTileColor: #000000, appleMobileWebAppCapable: yes, appleMobileWebAppStatusBarStyle: black, // configure the workbox plugin workboxPluginMode: InjectManifest, workboxOptions: { // swSrc is required in InjectManifest mode. swSrc: dev/sw.js, // ...other Workbox options... } } }一个典型的GenerateSW模式配置则更为简洁通常只需设置品牌相关字段module.exports { pwa: { name: My App, themeColor: #4DBA87, msTileColor: #000000, appleMobileWebAppCapable: yes, appleMobileWebAppStatusBarStyle: black, manifestOptions: { background_color: #ffffff, icons: [ { src: ./img/icons/android-chrome-192x192.png, sizes: 192x192, type: image/png } // ...更多图标 ] } } }在已有项目中安装插件对一个已经创建好的 Vue 项目执行vue add pwa该命令会运行 generator/index.js完成三件事为package.json添加依赖register-service-worker^1.7.2在入口文件如src/main.js注入import ./registerServiceWorker渲染模板文件——包括public/下的全套图标、robots.txt以及src/registerServiceWorker.js若项目启用了 TypeScript 插件还会自动把模板文件转换为.ts。其中 generator/template/src/registerServiceWorker.js 是应用侧注册 Service Worker 的入口它仅在NODE_ENV production时执行import { register } from register-service-worker if (process.env.NODE_ENV production) { register(${process.env.BASE_URL}service-worker.js, { ready () { /* 应用正在由 Service Worker 从缓存提供 */ }, registered () { /* Service Worker 已注册 */ }, cached () { /* 内容已缓存可离线使用 */ }, updatefound () { /* 正在下载新内容 */ }, updated () { /* 新内容可用请刷新页面 */ }, offline () { /* 无网络连接应用处于离线模式 */ }, error (error) { /* 注册失败 */ } }) }它使用register-service-worker库监听 Service Worker 生命周期的各个阶段你可以在这些回调中接入自己的业务逻辑例如在updated时弹出发现新版本提示。注入的 webpack-chain 规则插件通过api.chainWebpack注入以下 webpack 配置见 index.jsconfig.plugin(pwa)注册HtmlPwaPlugin置于 html-webpack-pluginhtml之后负责 HTML 标签与 manifest 注入config.plugin(workbox)仅在NODE_ENV production时注册使用GenerateSW或InjectManifest插件类生成/service-worker.js。注意若设置了环境变量VUE_CLI_BUILD_TARGET且其值不是app例如构建库或 Web Components 组件时插件会直接跳过注入避免为非应用产物生成 Service Worker见 index.js。Vue CLI UI 中的可视化配置插件还提供 Vue CLI UI 的可视化配置支持ui.js在 UI 的项目配置面板中可以看到名为 PWA 的配置卡片可图形化编辑workboxPluginMode、name、themeColor、msTileColor、appleMobileWebAppStatusBarStyle、manifestCrossorigin等字段并可直接打开vue.config.js与public/manifest.json文件。配置写入时若项目使用public/manifest.jsonUI 会同步把name、short_name、theme_color、background_color写回该文件。测试与验证仓库在 packages/vue/cli-plugin-pwa/tests下提供了pwaPlugin.spec.js与pwaGenerator.spec.js两组测试分别覆盖插件的 webpack 配置注入行为与生成器模板渲染行为可作为理解插件集成方式的参考样例。若你在自己的项目中使用本插件构建后可打开 Chrome DevTools → Application → Service Workers 面板检查/service-worker.js是否已注册、预缓存清单是否包含期望的资源。小结vue/cli-plugin-pwa把 PWA 集成的复杂度封装在vue add pwa一条命令与pwa一个配置对象之内生产环境由 Workbox 自动生成带预缓存能力的 Service Worker开发环境由 no-op 中间件保证本地调试不被旧缓存干扰HtmlPwaPlugin则统一完成图标、manifest 与移动端 meta 标签的注入。理解其默认值体系GenerateSW模式、#4DBA87主题色、manifest.json默认路径、图标默认路径等和配置合并优先级默认值 public/manifest.jsonpwa.manifestOptions即可在实际项目中快速产出符合各平台规范、可安装可离线的 PWA 应用。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考