离线环境下HTML单页应用的打包与打包物维护指南-html教程-PHP中文网

关键在于资源可寻址、可缓存、可更新，而非单纯打包成单文件；需规范相对路径、合理处理音频与图片内联限制、正确注册并配置service worker，且必须在https或localhost下运行。

离线环境下html单页应用的打包与打包物维护指南

单页应用（SPA）在离线环境能跑起来，关键不是“打包成一个文件”，而是资源可寻址、可缓存、可更新。直接把所有东西塞进一个 index.html 看似简单，但容易在图片加载失败、模块解析报错、音频不播放、缓存失效等环节翻车。

这个工具只处理相对路径资源，且默认跳过非同域、非相对、带查询参数的引用。

所有 src、href、import 必须是 ./xxx 或 ../xxx 形式；/assets/logo.png 或 https://cdn.com/sound.mp3 会被忽略
import 语句需为静态字符串，不能是模板字面量或变量拼接，否则 html-standalone 无法分析依赖树
ESM 动态 import() 不会被内联，对应 chunk 需手动确认是否已存在本地，或改用 fetch + eval（不推荐）或预加载策略
音频若大于 4MB，Safari 会拒绝解析 data URL，建议保留外链并配合 Service Worker 缓存，而非强求 base64

你在本地双击打开 HTML 文件时，地址栏显示 file:///xxx/index.html，此时 navigator.serviceWorker 为 undefined，任何缓存逻辑都无效。

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

调试阶段必须用本地服务器：比如 npx http-server -c-1（禁用缓存）或 python3 -m http.server 8000（但后者不支持自定义 MIME，manifest 会失效）
sw.js 必须与页面同源，且注册代码要加守卫：if ('serviceWorker' in navigator && location.protocol !== 'file:') { ... }
缓存名（cacheName）不能含空格、斜杠、控制字符；写成 v1-main 没问题，v1 main 或 v1/2 会导致 caches.open() 抛异常
不要缓存带 ?t=123 的 URL——SW 会把它当全新请求，反复拉取，填满 cache 存储且不命中

Chrome 和 Firefox 对 data URL 支持较宽松，但 Safari 在 iOS/macOS 上对单个 data URL 长度有硬性截断（约 5MB），超出部分被静默丢弃，表现为图片空白或 canvas 绘制失败。

用 npx html-standalone index.html --maxInlineSize 4194304 限高到 4MB，比默认 2MB 更稳妥
大图（如背景图、场景贴图）建议改用 Blob URL 方式动态创建，或通过 fetch 加载后转为 URL.createObjectURL()，避免塞进 HTML 源码
检查生成后的 HTML 文件大小：超过 15MB 容易触发某些杀毒软件拦截，或 Windows 资源管理器打开卡顿
用 grep "data:image/" game.html | wc -l 快速统计内联图片数量，结合 ls -lh game.html 判断是否过度内联

用户没看到新版本，往往不是代码没改，而是缓存没破、事件没监听、或 reload 被阻断。

applicationCache 已全平台废弃，Chrome 94+ 后 window.applicationCache 返回 undefined，别再查它
Service Worker 的 install 事件只在首次注册或 sw.js 内容字节变化时触发；改了 JS 文件但没动 sw.js？SW 不会重新缓存
updateready 事件必须配 self.skipWaiting() 和 clients.claim()，否则旧 SW 仍接管页面，新缓存不可见
调用 location.reload() 前，确保没有未完成的 IndexedDB 事务或 beforeunload 阻止刷新——否则页面卡住，用户以为“卡死”