用VuePack让 Vue 2 应用离线运行：PWA 渐进式 Web App 配置完整指南

【免费下载链接】vuepack:package: A modern starter which uses Vue 2, Vuex, Vue-router and Webpack 2 (and even Electron)项目地址: https://gitcode.com/gh_mirrors/vu/vuepack

VuePack 是一款现代 Vue 2 应用起步模板（starter），内置 PWA 渐进式 Web App 支持，让你零成本让 Vue 2 项目获得离线运行能力。本文带你快速了解 VuePack 的 PWA 配置原理、如何生成项目、构建验证离线效果，以及如何按需关闭它。

为什么需要 PWA 离线能力？

PWA（Progressive Web App，渐进式 Web 应用）可以让你的网页应用：

• 📴离线可用——断网时核心页面与静态资源依然能打开
• 📲添加到主屏幕——体验接近原生 App
• ⚡秒开加载——静态资源被 Service Worker 缓存，二次访问几乎即时响应

VuePack 基于 offline-plugin 实现了这套能力：构建时自动把所有 Webpack 产物缓存下来，无需你手写 Service Worker 逻辑。

快速创建支持 PWA 的 Vue 2 项目

先确保环境满足node >= 10和npm >= 6，然后通过 SAO 一条命令生成项目：

npm i -g sao jstransformer-handlebars sao vuepack new-project

也可以直接克隆模板：

git clone https://gitcode.com/gh_mirrors/vu/vuepack

生成过程中会询问是否启用 ESLint、Electron、TestCafe 等可选功能——PWA 支持默认开启，无需额外勾选，见初始化脚本 saofile.js。

项目生成后的目录结构（PWA 相关文件一目了然）：

├── build # webpack 配置（含 PWA 构建插件） │ └── webpack.prod.js ├── client # 客户端代码（含 PWA 运行时入口） │ ├── index.js │ └── pwa.js ├── dist # 构建产物 └── package.json

PWA 配置在哪里？4 个关键文件

VuePack 的 PWA 由 4 处配置协作完成，全部预先写好：

1️⃣ 依赖声明

template/package.json 中内置了offline-plugin依赖，构建时自动生成 Service Worker。

2️⃣ 生产环境才启用 PWA

template/client/index.js 中只在生产环境加载 PWA 运行时：

// Enable progressive web app support (with offline-plugin) if (process.env.NODE_ENV === 'production') { require('./pwa') }

这意味着开发阶段（npm run dev）完全不受缓存干扰，热更新正常工作，官方文档 docs/pwa.md 也强调了这一点。

3️⃣ 自动更新机制

template/client/pwa.js 注册了版本更新逻辑：

• onUpdateReady——检测到新版本时立即让 Service Worker 接管
• onUpdated——更新完成后自动刷新页面，用户无感知拿到新版

4️⃣ Webpack 构建插件

template/build/webpack.prod.js 中配置了OfflinePlugin：

new OfflinePlugin({ relativePaths: false, ServiceWorker: { events: true, navigateFallbackURL: '/' // 离线时回退到首页 }, AppCache: { events: true, FALLBACK: { '/': '/' } } })

navigateFallbackURL: '/'是关键配置——断网状态下访问任意路由，都会回退到已缓存的首页，配合 Vue-router 实现完整的单页离线体验。

一键构建并验证离线效果

构建与验证只需 3 步：

1. 构建生产包：npm run build（对应 build/webpack.prod.js）
2. 部署 dist 目录：把产物放到任意静态服务器（需支持 Service Worker，即 HTTPS 或 localhost）
3. 断开网络刷新页面——应用依然可访问；恢复网络后再刷新，会触发自动更新

💡 小技巧：构建产物使用[chunkhash]内容哈希命名（见 webpack.prod.js 第 25 行），天然支持长期缓存，与 PWA 缓存策略完美配合。

如何关闭 PWA 支持？

如果你的项目不需要离线能力，按 docs/pwa.md 的说明只需删除两处：

• 入口文件中的 PWA 加载逻辑：template/client/index.js
• Webpack 生产配置中的插件：template/build/webpack.prod.js

删除后重新构建，Service Worker 即不再生成。

核心文件速查表

总结

VuePack 让 Vue 2 项目获得 PWA 离线能力几乎"零配置"：依赖已声明、构建插件已接好、更新机制已写好，你只需要npm run build并部署，即可拥有可离线访问的渐进式 Web 应用。对于弱网环境的产品（工具站、文档站、内网系统），这套默认配置能直接带来体验提升。🚀

【免费下载链接】vuepack:package: A modern starter which uses Vue 2, Vuex, Vue-router and Webpack 2 (and even Electron)项目地址: https://gitcode.com/gh_mirrors/vu/vuepack