我给 TapMaker 做了一个不需要 Project ID 的本地预览器

最近在做 TapMaker 项目时，我遇到了一个很实际的工程痛点：远程预览适合最终验收，但对于高频调整 UI 和脚本而言，反馈链路实在太长了。

改一行 Lua 代码、微调一个按钮位置或是替换一张图片，如果每次都得走一遍完整的云端构建流程，花在等待上的时间甚至比真正写代码的时间还要多。于是我便开始琢磨：能不能在保留 Web Player 完整运行环境的前提下，只把项目资源重定向到本机目录？

经过一番折腾，最终做出来的工具就是 TapMaker Local Web。

一开始，我以为它需要 Project ID

最初的设计思路很直觉：让用户提供 Project ID、本地代码地址和 entry 入口，从而让预览器知道“当前要打开哪个项目”。

但在深入拆解通信协议后发现，这个思路其实把问题想反了。

远程环境之所以强制需要 Project ID，是因为服务端必须依赖它来检索项目元数据、校验权限并拉取对应的云端资源。而在本地预览场景中，资源已经由开发者明确指定——代码就在 --code 指定的目录中，启动入口也由 --entry 显式声明。既然完全不需要向远端发起查询，自然也就没有任何理由强求用户填写一个真实的 Project ID。

真正必要的输入其实只有两个：

本地代码目录 + Lua entry

虽然 Web Player 的内部协议仍然需要一个标识来区分本地缓存与会话，但工具完全可以基于代码目录和 entry 自动哈希生成一个稳定的本地命名空间。它并非真正的 Maker Project ID，既不需要用户费心维护，也不会产生任何远程网络请求。

这一调整让工具从一个“依赖特定项目上下文的辅助脚本”，转变为完全独立的通用开发工具：只要目录内存在可执行的 Lua 入口，就可以直接拉起预览。

我实际上劫持的是资源来源

这里的“本地预览”并非从零重新实现一套游戏引擎，也没有修改底层的 runtime。

工具的核心是在本地启动一个 localhost HTTP 服务，按照 Web Player 原生支持的数据格式，构造出对应的 manifest、项目配置及资源路由。Player 依然沿用官方原本的启动与渲染逻辑，只是原本需要从远程读取的项目资源，现在全部被重定向到了本机文件系统。

服务启动时，会自动扫描指定目录：

• 存在 .meta 时直接沿用既有的 UUID；
• 缺失 UUID 时，基于相对路径自动计算并生成稳定的本地 UUID；
• 根据文件内容计算 CRC32 校验码；
• 动态组装包含 Lua 脚本、图片、材质等资产的本地 manifest；
• 当 Player 请求具体资源时，直接从本地目录读取对应文件并返回。

因此，这个工具的核心本质并不是“去伪造一个线上项目”，而是将整个资源加载链条无缝替换为 localhost。

热重载也比预想中简单

为了满足日常高频调试的需求，必须解决保存代码后的即时刷新问题。

当前的实现并没有引入重型的文件监听机制（如复杂的文件系统 watcher），而是采用了轻量的心跳检查：页面每秒轮询一次 revision，服务端根据目录下文件的路径、修改时间（mtime）、文件体积以及 .meta 状态来判断内容是否发生变动。

一旦检测到文件变化，服务端便会立即重建对应的资源清单与 manifest，并通知页面触发整页 reload。由于资源请求路径中携带了 UUID 与 CRC 参数，文件变更后会自动获得全新的资源 URL，彻底避免了浏览器与 Player 的旧缓存干扰。

需要说明的是，这种方式并非 Lua 函数级的运行时热替换（Hot Patching），页面刷新后游戏运行状态会重置。但对于 UI 排版、入口逻辑、贴图替换和材质调整等高频视觉与逻辑校验场景而言，这种直观、稳定且排错成本极低的设计已经足够高效。

做成公开项目后，脱敏比功能更重要

最初的代码完全服务于个人私有开发环境，但在将其整理并开源为公共工具时，显然不能简单地把原目录直接复制出去。

在重构过程中，我最终将对外参数收敛为了最精简的 --code 与 --entry，彻底剥离了对私有工作区目录、内部项目清单、部署目标以及真实 Project ID 的隐式依赖。同时，针对本地服务补充了严格的安全边界与脱敏策略：

• 默认仅监听 127.0.0.1 本地回环地址；
• 严禁将本机绝对路径暴露在浏览器 URL 或公开参数中；
• 严格校验 entry 路径，拒绝任何尝试跳出代码目录（Path Traversal）的非法请求；
• 自动忽略与过滤 .git、.env、.project、.maker-mcp、虚拟环境及各类隐藏目录；
• 纯本地运行，绝不向外部网络上传任何本地项目文件；
• 开源仓库中附带的 Demo 经过彻底脱敏，不包含任何商业游戏资产、私有凭据或业务 UUID。

此外，我还为内置 Demo 补充了一套极简但真正可交互的界面，而不是仅仅在控制台打印一行启动日志。打开 Demo 页面后，你可以直接点击“开始游戏”、“+1 加分”与“重置”按钮，直观确认 UI 渲染、点击响应与热重载链路是否全部正常工作。

它解决的是反馈速度，不是正式验收

本地预览的核心价值在于极速反馈，能够覆盖 Lua 逻辑、UI 布局、图片贴图、音频音效、材质表现以及资源寻址等日常开发环节；但它绝不等于完整的线上生产环境。

工具内部所集成的本地账号体系与云变量 Mock，目的仅仅是保证基础调用链路不报错、生命周期能跑通，并不能代表真实的平台登录、云存档同步、排行榜上报、广告接入或权限鉴权等在线能力。一旦涉及这些平台级能力，依然必须回到官方提供的标准测试与发布流程中去。

明确这一边界至关重要：本地能够顺利跑通，仅说明当前代码可以被 Web Player 正确加载与解析；但这绝不等于已经通过了官方平台的集成验收。

现在怎么使用

如果你使用 Codex 等支持 Agent Skills 的工具，可以直接一键安装为 Agent Skill：

npx skills add iceprosurface/tapmaker-local-web-skill -g -a codex -y

然后向 Agent 提供两个核心参数即可：

使用 $tapmaker-local-web 预览本地项目。
代码目录：/absolute/path/to/game-content
入口：scripts/main.lua

当然，你也可以直接 Clone 仓库并通过 CLI 运行。关于 Runtime 模式选择、命令参数、单元测试及排错说明，均已整理在项目 README 中，这里就不再赘述。

项目地址：iceprosurface/tapmaker-local-web-skill

如果你在开发 TapMaker 项目时，也曾受困于“改一行代码就要漫长等待一次远端构建”的割裂感，不妨试试这套轻量高效的本地开发反馈环。