企业官网建设流程全解析

Three.js游戏上线前必过：threejs-qa-release的自动试玩、Canvas像素检测与视觉回归全解

【免费下载链接】threejs-game-skillsAgent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.项目地址: https://gitcode.com/gh_mirrors/th/threejs-game-skills

Three.js 游戏上线前最容易翻车的，就是"看着没问题、玩家一玩就崩"。在开源项目threejs-game-skills中，threejs-qa-release 技能包专为 Three.js 浏览器游戏提供上线前 QA：自动试玩 Bot、Canvas 像素检测脚本、Playwright 视觉回归基线，再配合移动端视口检查与生产构建验收，让 Agent 替你完成一套完整的发布验证 🚀

为什么截图"看起来对"不算验收通过？

很多开发者验收 Three.js 游戏时只看一眼截图：画面没黑屏、UI 没错位，就宣布完成。但 qa-release-checklists.md 里总结的常见上线失败恰恰都藏在"截图之外"：

• 测的是 dev server，却把没测过的生产构建发上线；
• 静态托管的 base path 把资源加载全打挂了；
• 移动端截图正常，但触摸控制根本无响应；
• Canvas 不空白，但那个端口上跑的是错误的 App；
• 调试面板、日志浮层直接暴露给了玩家。

所以 threejs-qa-release 的思路是：用可重复的自动证据替代"人肉看一眼"——能跑脚本的绝不靠目测。

一键Canvas像素检测：脚本替你验收画面

技能包内置了浏览器检查脚本 inspect-threejs-canvas.mjs，它会打开真实浏览器、等待 Canvas 出现、截图并做像素级采样，一条命令就能给出"画面到底渲没渲染"的客观结论：

node skills/threejs-qa-release/scripts/inspect-threejs-canvas.mjs --url http://127.0.0.1:5188 --mobile

它对新手友好的地方在于判定规则全部写死在脚本里：

• 非空白判定：统计有透明度像素的数量、颜色方差和颜色分桶数，低于阈值直接判low-variance失败——黑屏、纯色糊屏都逃不过；
• 量化视觉指标：输出颜色熵、边缘密度、亮度对比度（p95-p5）、主色占比等 metrics，这些数字可以直接作为"视觉评分卡"里的实测证据，而不是凭感觉说"画面还行"；
• 渲染预算对照：把 WebGL 渲染器的 draw calls、三角形数、几何体、纹理数与桌面/移动端起步预算逐项对比，超预算项会被如实列出；
• 移动端一条命令切换：加--mobile即按 iPhone 设备档案模拟，桌面和移动端各出一份报告；
• 状态可复现：通过--state active-play --seed 12345驱动游戏内测试钩子，冻结到指定状态再采样，不用人工实机操作。

只要画面异常或控制台报错，脚本就以非零码退出——这意味着它可以无缝挂进 CI 做门禁。脚手架游戏里还自带了对应的npm run inspect:canvas快捷命令（见 package.json）。

自动试玩Bot：让脚本替你"玩"一把

Canvas 像素检测只证明"游戏能渲染"，不证明"游戏能玩"。threejs-qa-release 用自动试玩（bot playtest）补齐这一环：用 Playwright 注入真实的按键输入，让脚本化身玩家跑完整局，再量化分析它表现如何 🤖

模板位于 bot-playtest.template.ts，拷贝改名后按自己的玩法微调输入脚本即可：

cp tests/bot-playtest.template.ts tests/bot-playtest.spec.ts npx playwright test tests/bot-playtest.spec.ts

playtest-bot.md 定义了每项指标的含义，非常值得新手对照理解：

进阶玩法是难度公平性验证：让 Bot 分别以 0ms 和 300ms 反应延迟跑两局，对比存活时间——慢速 Bot 居然活得更久，说明难度只是装饰；快速脚本也活不过第一波威胁，说明开局不公平。另外两条实用提醒：WebGL 游戏请保持workers: 1运行（见 playwright.config.ts），以及无头模式下的 FPS 只能当功能验证、不能当性能证据。

视觉回归基线：截图对比防视觉走样

画面能渲染、游戏能玩，最后一道关是别让后续改动悄悄毁掉视觉——HUD 文字溢出、菜单错位、生成资产消失，都是典型的"回归"。

visual-test-harness.md 给出了清晰的取舍原则：原型阶段不必急着建基线；但游戏一旦走到发布级、UI 重、生成资产多，就值得上 Playwright 截图对比。核心前提是确定性：脚手架游戏已内置__THREE_GAME_TEST_HOOKS__（seed 随机种子、setState 切状态、截图时暂停、隐藏调试 UI），模板 visual-regression.template.ts 会在钩子缺失时直接大声报错，避免对着动态场景截图导致每次必 diff。

使用上只有两条命令，首次生成基线、之后持续对比：

npx playwright test tests/visual-regression.spec.ts --update-snapshots npx playwright test tests/visual-regression.spec.ts

阈值设置有一条经验法则：稳定的 UI/菜单状态用低maxDiffPixelRatio，WebGL 抗锯齿差异允许略放宽，但绝不能松到让真实布局或资产问题蒙混过关。报告里要写清：覆盖了哪些状态、更新/对比命令、基线路径、遮罩与阈值理由、残余抖动风险。

生产构建与上线发布清单

最后一环是把"开发服务器上的成功"变成"线上可发布的成功"。release.md 的发布清单浓缩为六件事 ✅

1. npm run build通过，且用npm run preview或静态服务器测构建产物而非 dev server；
2. Vitebase路径与资源 URL 和目标托管环境一致；
3. 调试面板、诊断浮层、测试快捷键全部被门控或移除；
4. 生产预览下桌面与移动端视觉检查通过，主交互路径可用；
5. 审查包体积与大资源，确认 API key 没有混进客户端代码和构建产物；
6. 最终报告包含：命令、截图/工件、已知风险、部署方式。

配套的 visual-verification.md 则规定了视觉验收动作：控制台零错误、Canvas 显示尺寸与缓冲区尺寸均非零、截图后做像素采样、桌面/笔记本/移动三档视口逐一过、resize 后相机宽高比正确、HUD 文字不重叠不裁切。

如何开始：安装并启用技能

如果你用 Codex 或 Claude Code 等 Agent，安装只需一条命令：

npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a codex -g -y

（Claude Code 把-a codex换成-a claude-code即可。）也可以克隆仓库后用自带安装器./install.sh --all。之后在提示词里点名threejs-game-director，由总导演按 SKILL.md 的流程调度 QA：装依赖、跑构建、开预览、抓控制台错误、像素检测、双端截图、触发关键输入路径、判定视觉回归与 Bot 试玩，最后以"通过/不通过 + 证据"开头输出报告。

💡 上手建议：第一次跑通"像素检测 → 试玩 Bot → 视觉基线"这条链路后，把三条命令固化进你的发布流程。此后每次改动，证据先行、结论在后，上线风险自然降下来。

主要参考文件：threejs-qa-release/SKILL.md、qa-release-checklists.md、bot-playtest 清单、Canvas 检测脚本、视觉验证清单。

【免费下载链接】threejs-game-skillsAgent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.项目地址: https://gitcode.com/gh_mirrors/th/threejs-game-skills