《屋滴乖乖》原本是一个 Cocos 项目里的子玩法。为了发布到小红书小工具，我们把它拆成了一个完全离线、不依赖任何服务器的 H5 包。这篇记录整个过程中踩到的坑，供准备做同类发布的朋友参考。
为什么要拆成纯 H5
平台小工具对包体、启动速度和网络请求都有限制。拆出来以后：
- 最终包体约 16 MB，用原生 HTML/CSS/JS 实现，不再依赖引擎运行时；
- 不需要任何网络请求，审核更顺利；
- 存档完全放在本地，玩家打开就能玩。
坑一：资源路径必须是相对路径
打包工具默认生成以 / 开头的绝对路径。小工具的运行目录不是域名根目录，绝对路径会全部 404。Vite 项目在配置里加一行：
export default defineConfig({ base: './' });
上线前用一个简单的检查，确保 index.html 里没有以 / 开头的资源：
grep -E '(src|href)="/[a-z]' dist/index.html
坑二：音频在用户交互前不会播放
移动端浏览器禁止自动播放声音。第一次点击屏幕之前，所有音频都会静默失败。解决办法是在首次触摸时「解锁」音频上下文：
window.addEventListener('pointerdown', () => audioContext.resume(), { once: true });
坑三：安全区与平台胶囊按钮
小工具顶部右侧有平台自己的胶囊按钮，会盖住游戏右上角的图标。需要把顶部 HUD 下移，并在右上角为胶囊按钮留出空白区域，具体尺寸以平台文档和真机为准。
坑四：平台接口要做降级
「关注作者」奖励依赖小红书注入的 window.xhs 接口。为了让同一个包也能在普通浏览器里运行（比如本站的试玩），我们封装了一层兼容：
const platform = window.xhs ?? {
follow: () => Promise.resolve({ ok: false, reason: 'unsupported' }),
};
在普通网页里，关注按钮会自动隐藏，其余玩法不受影响。
坑五：离线存档的边界情况
- 体力恢复按真实时间计算，玩家改系统时间就能刷体力。可以记录上次的时间戳，发现时间倒退时不发放恢复；
- 存档写入要做成「先写临时键，成功后再替换」，避免写到一半被系统杀掉导致存档损坏；
- 浏览器清理缓存会丢档，可以在设置里提供导出和导入。
上架前检查表
- 所有资源都是相对路径
- 断网状态下能完整启动和游玩
- 首次点击后音乐和音效正常
- 顶部胶囊按钮区域没有可点击的 UI
- 平台接口不存在时功能自动降级
- 存档在杀进程后仍然完好
- 包体大小在平台限制以内
做完这些，同一个 H5 包可以同时用于平台发布、官网试玩和分享链接，一次构建多处复用。
