site-check

网站检查

动画页面在构建它时所用的单个浏览器标签页中可能看起来完美无缺，但在其他地方却会出问题：Safari 中画布一片空白、手机上画面被裁切、滚动影片出现接缝，或笔记本电脑上的帧耗时达到 40 ms。这项技能会在多个实际浏览器和多种尺寸下，以访客的视角检查页面，并附上图片报告问题。

工具

scripts/check.py 通过 Playwright 驱动无头 Chromium（使用真实 GPU）和 WebKit。

python3 scripts/check.py http://127.0.0.1:8000/ --out shots \
  --widths 1440,768,390 --browser both \
  --query "view=front" "view=aerial&light=night" \
  --scroll-steps 6 --ready "window.__ready === true"

选项	含义
--query	附加到 URL 的查询字符串；每个字符串都会在每种宽度下各截取一次。为页面提供深层链接（?view=、?light=、?step=），确保每种状态都可访问
--widths	1440（笔记本电脑）、768（平板）、390（手机，使用触控和 DPR 2 模拟）
--browser	chromium、webkit（Safari 使用的引擎）或 both
--scroll-steps N	还会截取 N 个间距均匀的滚动位置，适用于滚动驱动的页面
--ready	页面实际渲染完成后会返回 true 的 JS 表达式
--wait	等待页面稳定后再测量的秒数

输出：每次截取对应一个 PNG、report.json，以及标注了每张截图的 sheet.jpg；有问题的截图会用红色标注。如果任何一次截取出现页面错误、请求失败或返回 4xx/5xx、画布空白或水平溢出，脚本就会以 1 退出。每次截取还会在最宽的尺寸下进行一次减少动态效果测试。

需要 Python 3.9+、pip install playwright pillow，以及 python3 -m playwright install chromium webkit。请通过 HTTP 提供页面服务（ES 模块和视频定位都需要 HTTP），使用 scripts/serve.py DIR --port 8000；它支持 Range 请求，而 python3 -m http.server 不支持。

阅读报告

• 每帧毫秒数是根据真实的 60 帧测得的。低于 16.7 即为 60 fps；笔记本电脑 GPU 上的无头浏览器应接近 16.7（垂直同步），因此更高的数值意味着确实存在性能开销。请比较不同运行结果。如果报告显示渲染器是 SwiftShader 或 llvmpipe，则没有使用 GPU，帧耗时数据没有意义。
• 调用次数 / 三角形数来自 window.__app.renderer（three.js），按整帧统计，包括每个后期处理通道。请在此处公开渲染器，以便检查程序读取。
• ready_s 是页面设置就绪标志所用的时间。在性能良好的机器上超过 3 s，意味着手机上加载器显示时间过长。
• 画布空白表示可见画布呈现单一纯色：可能是 WebGL 上下文创建失败、着色器在该浏览器中编译失败，或是在资源加载前就绘制了帧。

接下来检查

数值可以发现故障；画面是否难看，则要靠你的眼睛判断。打开 sheet.jpg，检查每张截图是否存在以下问题：

• 主体在手机截图中被裁切或显得很小。竖屏上的 3D 场景应扩大垂直视野；布局应重新堆叠。
• 文字叠在繁杂图像上，缺乏对比度。
• UI 遮住主体，或落在手机的主页指示条下方。
• 光照状态变成一片漆黑或过曝成一片白。
• WebKit 截图与 Chromium 不同：颜色（Safari 会忽略一些色彩空间提示）、缺少透明效果（Safari 无法播放带 VP9 alpha 的视频）、字体。

脚本无法独立完成的检查

请手动执行，或使用低帧率（--fps 8）的 frame-capture 执行；这种方式快速且精确：

• 接缝和循环。 快速上下拖动每段滚动影片；观察每个连接处以及每个循环的衔接。scroll-film/scripts/prep.py seams 会为接缝评分并给出数值。
• 固定区段释放。 每个固定区段结束时，页面都必须能继续滚动，且不能突然跳动。
• 长时间运行。 让页面运行一分钟，来回切换灯光预设，并多次调整窗口大小；帧耗时不应逐渐增加（泄漏的几何体和纹理会在 report.json 中体现为计数持续上升）。
• 限速网络下的首次加载。 在网络限速的情况下，首次绘制应显示主视觉图的海报或第一帧，而不是空白页面。
• 交互。 旋转、缩放、悬停状态、每个控件的键盘焦点，以及手机上的触控。

环境陷阱

• 隐藏的嵌入式浏览器预览或后台标签页会限制或冻结 requestAnimationFrame。页面在那里“无法动画”也可能完全正常。无头浏览器没有这个问题。
• python3 -m http.server 会忽略 Range 请求，因此视频无法跳转，随滚动播放的视频也会卡住。请使用能够响应此类请求的服务。
• 升级后缺少 Playwright 浏览器构建版本：脚本会回退到 Playwright 缓存中的任意 Chromium；CHROME_PATH 可覆盖此设置。

反馈问题

先说明故障，并按影响访客人数排序：先列出错误和空白画布，然后是手机布局、Safari 差异、性能问题，最后是细节优化。附上联系表。说明哪些内容未经检查（没有真实手机、没有 Windows GPU、没有慢速网络），不要暗示已检查。