Slidev 离线部署实战开启 pwa 预缓存让整份演示文稿在无网络时也能完整播放【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev如果你需要在陌生或受限的机器上演讲、在信号不稳的会场展示幻灯片或者干脆想把一份自托管的演示打包成断网也能跑的应用那么 Slidev 的pwa选项正是为此设计的它通过slidev build生成一个基于 Service Worker 的渐进式 Web 应用PWA把整份演示文稿的所有资源预先缓存下来。读完本文你将掌握pwa选项的完整配置语义、vite-plugin-pwa的按需安装流程、预缓存的底层实现原理以及大媒体文件、远程资源等边界情况的处理方案。本功能对应的官方文档见 docs/features/pwa.md自 v52.17.0 起提供属于可独立使用的可选特性之一可在 特性索引 中浏览全部特性。为什么幻灯片需要离线优先一次演讲可能发生在各种不可控的环境中主办方提供的笔记本权限受限、会议现场 Wi-Fi 时断时续、甚至根本没有网络。普通 Web 版幻灯片在加载后会按需请求图片、视频等资源一旦中途断网后续页面就可能加载失败。Slidev 的解法很直接以opt-in的方式开启pwa后slidev build构建出的产物会携带一个 Service Worker由vite-plugin-pwa和 Workbox 驱动它会把每张幻灯片的全部资源都预缓存precache——包括 JavaScript、CSS、HTML以及所有图片、视频和音频。只要演示文稿被成功访问过一次之后的整场演讲就完全从缓存中读取不再有逐页拉取资源、中途卡壳的风险。快速上手在 headmatter 中开启 pwapwa是一个面向整份演示的配置项只需在第一张幻灯片的 frontmatter即 headmatter见 headmatter 配置中开启即可--- pwa: true ---pwa选项的取值既可以是布尔值也可以是字符串用来精细控制 Service Worker 在哪个阶段生效取值行为false默认不生成 Service Worker完全关闭true开发服务器和构建产物中均启用build仅构建产物启用离线部署最常用的组合dev仅在开发服务器中启用从类型定义可以印证上述语义在 packages/types/src/frontmatter.ts 中该字段被声明为pwa?: boolean | dev | build。而具体的模式匹配逻辑位于 packages/slidev/node/vite/pwa.tsmatchMode只有在配置值等于true、或与当前构建模式dev/build字符串相等时才判定为启用。由于预缓存全部资源开销较大pwa默认是关闭的配置参考文档 docs/custom/index.md 中同样标注默认值为false需要使用者有意开启。它最有价值的应用场景是与 部署与托管 中介绍的slidev build配合构建并自托管一份希望能在离线状态下正常播放的演示。安装 vite-plugin-pwa可选依赖的自动安装与手动安装PWA 能力由vite-plugin-pwa提供但它被设计为可选的 peer dependencyoptional peer dependency——Slidev 默认不安装它因此未开启pwa的演示项目永远不会下载这个包。当你第一次在配置里把pwa设为启用值并运行命令时Slidev CLI 会检测到该包缺失并弹出交互式提示请你确认安装? The pwa option requires the vite-plugin-pwa package, which is not installed in your project. Install it now? › (Y/n)确认提示后Slidev 会使用你项目当前的包管理器自动安装它如果 Slidev 本身是全局安装的则会安装到全局环境中。这一按需解析与提示安装的完整流程实现在 packages/slidev/node/vite/pwa.ts 的resolveVitePWA函数中先通过importOptionalDependency尝试懒加载包失败则调用promptForOptionalInstallation发起安装提示并重新加载若最终仍未获得VitePWA工厂函数则抛出明确的错误信息。需要注意在非交互式环境如 CI中无法弹出提示框此时应提前手动安装依赖npm i -D vite-plugin-pwa与之对应当pwa处于关闭状态时createPWAPlugin 会返回一个极简的slidev:pwa-register-stub占位插件把客户端用到的virtual:pwa-register虚拟模块解析为一个空操作见 createPWARegisterStubPlugin保证开发服务器中受保护的动态import仍可解析同时完全不需要拉取vite-plugin-pwa依赖。工作原理从构建产物到完全离线的缓存链路构建期Vite 插件与编译期特性开关在 packages/slidev/node/vite/index.ts 中createPWAPlugin(options)被加入到 Slidev 的 Vite 插件列表。同时packages/slidev/node/options.ts 会把启用状态编码进编译期常量__SLIDEV_FEATURE_PWA__其值由matchMode(config.pwa)决定。这个编译期开关是无成本运行的关键客户端代码中所有相关分支都受__SLIDEV_FEATURE_PWA__保护例如 App.vue 中v-if__SLIDEV_FEATURE_PWA__的条件渲染、setup/main.ts 的按需初始化。当pwa关闭时这部分代码会在打包时被tree-shaking 摇掉——官方文档明确承诺关闭状态下插件是彻底的 no-op注册逻辑与右下角状态指示器都不进入最终包体运行时零开销。插件配置Workbox 与 Manifest 的默认值真正启用时Slidev 以如下配置调用VitePWA见 packages/slidev/node/vite/pwa.ts这些默认值直接决定了离线可用的实际边界registerType: autoUpdateService Worker 采取自动更新策略避免演讲中途使用过期缓存injectRegister: null插件本身不注入注册脚本改由 Slidev 客户端逻辑自行注册见下文workbox.maximumFileSizeToCacheInBytes: 100 * 1024 * 1024把 Workbox 预缓存的单文件大小上限从默认值提升到100 MB避免大视频等文件被静默跳过workbox.globPatterns预缓存 glob 覆盖js/css/html、woff/woff2/ttf字体、常见图片格式png/jpg/jpeg/svg/gif/webp/avif/ico以及常见音视频格式mp4/webm/ogv/mov/m4v/mp3/wav/ogg/oga/m4a/aac/flac/opus/webaworkbox.navigateFallback: index.html对 SPA 导航提供回退同时通过navigateFallbackDenylist排除/presenter、/notes、/overview、/print、/export等内部路由前缀manifest生成的 Web 应用清单包含演示文稿标题、start_url即部署base路径、display: fullscreen以及#121212的主题色与背景色。值得注意的是清单中刻意没有包含任何图标——这并非疏漏而是设计约束离线功能本身绝不能依赖远程/CDN 资源而演示文稿自己的favicon配置可能是一个 URL。不放置图标能让清单始终有效同时保证这一特性可以纯离线运行。运行期Service Worker 注册与状态指示客户端侧的注册逻辑位于 packages/client/setup/pwa.tssetupPWA()首先以__SLIDEV_FEATURE_PWA__守卫然后动态import(virtual:pwa-register)并调用registerSW({ immediate: true, onOfflineReady })其中onOfflineReady回调会把右下角的离线就绪提示在4 秒后自动消失。指示器的真实界面实现在 packages/client/internals/PwaIndicator.vue一个固定在右下角、带半透明模糊背景的小标签。它的完整运行体验是部署并访问slidev build的产物后Service Worker 在后台静默下载并缓存全部资源此时右下角显示Caching for offline…预缓存完成后短暂显示Ready offline随后自动淡出此时断开网络并刷新页面整份演示——包括 HTML、图片与视频——都会直接从缓存中提供服务。离线能力的边界与注意事项预缓存并不是万能离线以下几点决定了它的适用前提只有构建产物会被预缓存。在构建时输出emitted进产物的文件才会进入缓存运行时从远程或 CDN 拉取的资源无法离线获取。若希望远程图片也能离线播放可结合 Bundle Remote Assets 特性它会在构建阶段把远程资源下载并打进产物。清单不包含图标。如前述为保证不依赖任何远程/CDN 图标生成的 Web 应用清单有意不含icons字段但仍是合法清单。大媒体文件的容量保障。得益于 100 MB 的单文件上限与覆盖常见图片/视频/音频扩展名的预缓存 glob体积较大的媒体不会因 Workbox 默认限制而被静默跳过。离线拖拽视频进度可能受限。预缓存的媒体以完整缓存响应full cached response方式提供因此从头播放可以正常工作而离线状态下对视频进行拖动/跳播seeking可能需要额外的 range-request 处理。推荐组合与小结一句话总结这套方案的落地路径在演示文档第一页 headmatter 写入pwa: build或pwa: true提前或按 CLI 提示安装vite-plugin-pwa执行slidev build后把产物托管到任意静态服务器——首次访问后即进入完全离线可用状态。若演示中包含远程图片再叠加 Bundle Remote Assets配合 部署与托管 指南可完成整套自托管流程。从实现层面看这一特性是编译期开关 按需可选依赖 客户端守卫三者的精巧配合pwa关闭时从依赖到代码都被彻底旁路开启时则由 Workbox 承担预缓存、由vite-plugin-pwa承担 Service Worker 生成最终换来的是演讲稿开场前一次加载、整场演讲无忧播放的可靠体验。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
