godot-platform-web

绝对不要做的事（Web 专家规则）

持久化与存储

• 绝对不要单独使用 FileAccess 进行 Web 持久化保存——优先使用 web_local_storage_wrapper.gd（通过 JavaScriptBridge 使用 localStorage / IndexedDB）。
• 绝对不要假设 localStorage 永久可用——生产环境中应实现云端保存回退方案。

渲染与逻辑

• 绝对不要在 Web 中使用 Forward+ 渲染器——请使用 Compatibility（WebGL 2.0）。
• 绝对不要阻塞浏览器事件循环——长时间同步任务会导致“页面无响应”。在可用时使用 await / 线程工作器。
• 绝对不要忽略 COOP/COEP——线程 / SharedArrayBuffer 需要跨源隔离。

用户体验与安全

• 绝对不要忽略标签页失焦——在 visibilitychange 时暂停音频。
• 绝对不要在没有点击的情况下触发全屏 / 鼠标锁定——必须在用户手势中触发。
• 绝对不要在 HTML 外壳中使用绝对路径——使用相对路径以支持子目录托管。

---

托管检查清单（流程）

1. HTTPS——许多浏览器 API（剪贴板、某些存储策略、安全上下文）都需要 HTTPS。
2. COOP / COEP——启用线程 / SharedArrayBuffer 时提供隔离标头（参见 Web 导出文档）。
3. 相对外壳路径——自定义 index.html / PCK/WASM URL 必须使用相对路径，才能支持 /game/ 子路径。
4. beforeunload——存在未保存的进度时，接入 web_navigation_guard.gd。
5. Compatibility 渲染器 + 纹理压缩——桌面浏览器：视情况使用 S3TC/BPTC；控制粒子和绘制预算。

可用脚本

必需：保存数据时，请加载 web_local_storage_wrapper.gd——不要粘贴 JavaScriptBridge.eval("localStorage.setItem...") 字符串写法。

web_local_storage_wrapper.gd

通过 get_interface + JSON 实现配额安全的 localStorage（不使用 eval 字符串插值）。

web_javascript_bridge_callback.gd

使用 create_callback 实现双向 JS↔GD 通信（保持回调引用有效）。

web_responsive_canvas_adaptor.gd

将画布调整为浏览器视口大小。

web_browser_input_guard.gd

抑制上下文菜单 / 空格键滚动默认行为。

web_resource_lazy_loader.gd

远程 PCK/资源获取模式。

web_clipboard_interface.gd

通过 Navigator API 异步访问剪贴板。

web_visibility_auto_pause.gd

标签页隐藏时暂停引擎 / 音频。

web_navigation_guard.gd

针对未保存进度的 beforeunload 保护。

web_external_url_opener.gd

使用 noopener 调用 window.open。

web_performance_profiler.gd

将 VRAM / 绘制统计信息输出到 JS 控制台。

scripts/ 中还有

• platform_web_patterns.gd — 各类 Web 功能门控。
• web_bridge_sync.gd — 结构化桥接同步辅助工具。
• web_json_rpc_bridge.gd — JSON-RPC create_callback 桥接（保持引用有效）。

专家须知的原因（关键）

**注意：**绝不要通过 JavaScriptBridge.eval("localStorage.setItem('%s')" % data) 持久化数据——这会导致注入 / 转义错误。请使用 web_local_storage_wrapper.gd。

• PWA 更新——当 pwa_needs_update() 时调用 pwa_update_available → pwa_update()。
• WebGPU——不是 Godot 4.x 的 Web 渲染器；请使用 Compatibility（WebGL 2.0）发布。
• JSON-RPC 宿主页面——结构化双向桥接：web_json_rpc_bridge.gd。

深入了解（按需加载）

PWA 生命周期、JSON-RPC 桥接、localStorage 反模式、大小调整参数 — references/web-elite-patterns.md。

加载外壳（自定义 HTML）

<div id="loading-screen">
    <div class="progress-bar"><div id="progress" style="width: 0%"></div></div>
    <p id="status-text">Loading...</p>
</div>
<script>
const engine = new Engine(CONFIG);
engine.startGame({
    onProgress: function(current, total) {
        const percent = Math.floor((current / total) * 100);
        document.getElementById('progress').style.width = percent + '%';
        document.getElementById('status-text').innerText = `Loading ${percent}%`;
    }
}).then(() => {
    document.getElementById('loading-screen').style.display = 'none';
});
</script>

功能门控

if OS.has_feature("web"):
    # Web-only: storage wrapper, visibility pause, navigation guard
    pass

大小／性能调节项

[rendering]
textures/vram_compression/import_s3tc_bptc=true
textures/vram_compression/import_etc2_astc=true

• 以中端浏览器达到约 60 FPS 为目标；减少粒子、绘制调用和超大纹理。
• 通过对文档／源文件应用排除筛选器，将下载大小控制在合理范围内（约 50MB）。

PWA 更新钩子

func _ready() -> void:
    if OS.has_feature("web"):
        JavaScriptBridge.pwa_update_available.connect(_on_pwa_update)

func _on_pwa_update() -> void:
    if JavaScriptBridge.pwa_needs_update():
        JavaScriptBridge.pwa_update()

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接； 仅在将工作路由到相关领域时加载相关技能——不要预先加载整个技能网络。

官方文档

• 导出到 Web — 导出预设、Compatibility／WebGL 限制，以及线程／SharedArrayBuffer 为何需要 COOP／COEP 隔离。
• Web 导出 — 在接入仅限浏览器的 API 之前，了解 HTML5 托管限制的平台概览。
• JavaScriptBridge 单例 — 双向 GD↔JS 桥接的 eval、get_interface 和 create_callback 约定。
• Web 导出的自定义 HTML 页面 — 使用相对资源路径和自定义加载外壳，确保构建可在子目录下运行。
• HTML5 外壳类参考 — 自定义加载屏幕使用的 Engine／startGame 进度回调。
• JavaScriptBridge — PWA 更新信号以及剪贴板／下载辅助功能；必须保持 JS 回调引用有效。
• 3 种渲染方法简介 — Web 导出为何应采用 Compatibility（WebGL 2.0），而非 Forward+。
• Godot 项目中的文件路径 — 相较于 localStorage／IndexedDB，为何在浏览器沙盒中使用 user://／FileAccess 持久化并不可靠。
• 保存游戏 — 在将存档数据封装到浏览器存储 API 之前，先对其进行序列化并添加版本信息。
• 多种分辨率 — 用于响应式 Web 视口的拉伸／宽高比／内容缩放设置，以及对应的 HTML 画布调整策略。
• 处理退出请求 — 可映射到标签页 visibilitychange 和 beforeunload 防护的暂停／恢复生命周期。
• GPU 优化 — 决定 WebGL 帧耗时的绘制调用、纹理和粒子预算。

相关技能

前置条件

• godot-project-foundations — 每个 HTML5 导出分支都依赖的功能标签（web）、Compatibility 渲染器默认设置和显示拉伸设置。
• godot-input-handling — 在屏蔽浏览器默认行为（右键菜单、空格键滚动）或重新映射画布焦点之前，先明确 InputEvent 的所有权。
• godot-save-load-systems — localStorage 封装不得临时自行编造的版本化存档所有权和云端回退钩子。

补充

• godot-platform-mobile — 当同一构建在移动浏览器中运行时，可能会用到的触控和生命周期模式。
• godot-platform-desktop — 当一个项目同时面向桌面和 Web 时，确保原生桌面路径正常运行。
• godot-audio-systems — 当标签页不可见时必须暂停播放以避免后台音频时使用的总线和语音控制。
• godot-performance-optimization — 在采用 Compatibility 和压缩后，WebGL 性能预算仍无法达到 60 FPS 时，用于分析性能并降低 CPU/GPU 开销。
• godot-ui-containers — 随浏览器画布在桌面和手机 Web 页面上调整大小，仍能保持易读的控件布局。
• godot-autoload-architecture — 为 JavaScriptBridge 管理器、存储封装器和始终启用的可见性保护机制提供单例归属。
• godot-multiplayer-networking — 游戏托管在浏览器中后，用于取代局域网假设的 WebSocket/WebRTC 对等连接。
• godot-resource-data-patterns — Web 上远程按需加载获取流程所依赖的 PCK/资源打包约定。

下游 / 使用方

• godot-export-builds — 在确定浏览器 API 和 Compatibility 设置后，用于 CI 预设、构建产物托管和体积限制。

主模块

• godot-master — 库路由器和镜像模块入口，用于发现与此平台技能并列的其他领域模块。