开源项目地址：https://github.com/sznswjr/kiseki_engine KisekiEngine 渲染 Bug 排查实录：从“立方体全亮、地面纹理消失”到 7/7 自动化测试全通过 背景 KisekiEngine 是一个基于 Metal 的 3D 图形引擎，实现了 Blinn-Phong 点光源光照、纹理贴图、OBJ 模型加载和多物体场景渲染。在完成所有功能后，用户报告了两个渲染问题： 立方体全亮：没有明暗面，整个立方体看起来亮度均匀 地面纹理消失：设置了 ground.png 纹理但地面显示为纯色 第一轮尝试：盲修（失败） 假设 1：uniform 布局不对齐 怀疑 C++ 端 simd_float3（16 字节）和 Metal shader 端 float3（12 字节）的对齐差异导致数据错位。 操作：将所有 simd_float3 + padding 改为 simd_float4 打包。 结果：编译通过但问题未解决。事后验证发现结构体偏移量实际上是一致的（offset 80 处 hasTexture），这个修改虽然没直接修到 bug，但让布局更安全了。 假设 2：无纹理物体残留纹理 怀疑光源球体（无纹理）渲染后残留了之前的纹理绑定。 操作：对无纹理物体显式调用 [encoder setFragmentTexture:nil atIndex:0]。 结果：问题仍未解决。 教训 盲修效率极低。每次修改都是猜测，无法验证是否真正触及根因。 转折点：先做验证工具，而不是继续猜 真正改变排查策略的一句要求是： 先不要解决问题，先设计一套测试工具验证修复到底正不正确。 这一步很关键。对于图形渲染问题，仅凭肉眼看窗口往往不够，必须建立一套可以重复执行的观测和验证机制。 第二轮：构建诊断系统 1）Debug Mode Shader 利用 Metal function constants 实现了多种 shader 可视化模式，用来分别观察不同信号：