PixiJS V4 圆柱体效果实现故障总结报告

1. 事故摘要

在将 PixiJS V8 的圆柱体效果移植到 V4 版本 (Legacy) 的过程中，经历了多次代码迭代和反复调试。虽然最终实现了预期的视觉效果（带光影的 3D 圆柱投影、适配画布的缩放），但耗时较长，未能一次性高效解决。

主要痛点在于：初期圆柱体形状无法持久显示（自动变回平面），后期缩放比例和居中位置反复不准（导致“看不到”效果）。

2. 故障现象与排查过程

阶段一：Mesh 创建方式失效

• 尝试：最初试图完全手动构建 PIXI.mesh.Mesh，手动计算 vertices、uvs 和 indices。
• 问题：V4 版本的 Mesh API 与现代版本差异较大，手动构建的拓扑结构容易出错，导致画面空白或渲染异常。
• 调整：转而使用 PIXI.mesh.Plane，因为它能自动生成标准网格拓扑。

阶段二：顶点数据被静默重置（关键卡点）

• 现象：修改了 Plane.vertices 后，画面依然显示为平面，或者圆柱效果一闪而过。
• 原因：这是 PixiJS V4 Plane 组件的一个内部特性。每当 Texture 更新或组件触发刷新时，它会调用内部的 refresh() 方法，强制将 vertices 重置为矩形平面，覆盖了我们的自定义修改。
• 解决：采取了“猴子补丁” (Monkey Patch) 策略，在创建 Plane 后立即覆盖其 refresh 和 _refresh 方法为空函数，从而保护了自定义顶点数据。

阶段三：缩放与视口计算混乱

• 现象：解决了形状问题后，圆柱体要么充满了整个屏幕（看不到顶部和底部的透视弧度），要么位置偏离。
• 原因：在计算缩放比例 scale 时，参考系选择错误。
  • 一度使用了 DOM 元素的 clientWidth/clientHeight，这在高 DPI 屏幕或 CSS 拉伸下不可靠。
  • 或者是混用了 app.renderer.width（物理像素）和逻辑坐标，导致在 resolution > 1 时计算偏差。
• 最终解决：摒弃不稳定的动态尺寸，回归到应用初始化时的逻辑尺寸 (800x600) 作为唯一真理来源。基于固定的 800x600 计算缩放和居中，再留出充足的 Padding (0.65)，确保了内容在任何 CSS 布局下都保持正确的相对比例。

3. 根本原因分析 (Root Cause Analysis)

1. 对遗留 API (PixiJS V4) 的隐性行为认知不足：未能预判 Plane 组件会自动重置顶点数据，导致在前几次迭代中认为是算法错误，实则是数据被覆盖。
2. 视口坐标系概念混淆：在 WebGL/Canvas 开发中，存在“物理像素”、“逻辑像素 (CSS)”和“内部渲染缓冲区”三套尺寸。在调试缩放问题时，没有第一时间锁定“逻辑尺寸”作为锚点，而是在 DOM 尺寸和渲染器尺寸之间摇摆，浪费了调试时间。

4. 经验教训与改进措施

1. Hack 遗留代码需谨慎：在使用高封装组件（如 Plane）做非标准用途（如自定义顶点变形）时，应第一时间检查其源码或文档是否有“自动更新/重置”的机制。
2. 建立稳定的坐标参考系：在处理 Canvas 内容适配时，应始终基于**设计分辨率（逻辑尺寸）**进行计算，而不是依赖容易受环境影响的 DOM 属性。
3. 可视化调试：以后遇到类似“看不到效果”的问题，应更早地调小缩放比例（如直接设为 0.5），先确认“东西在不在”，再调整“东西多大”，而不是在全屏填充状态下盲目猜测。

---

报告人: Antigravity
日期: 2026-02-03

贡献者

ruan-cat

页面历史

最后编辑于 20 分钟前

查看完整历史

b923836-docs: 添加 Pixi v4 圆柱体调试报告