threejs-debugging

Three.js 调试

先复现。将已安装的源码和官方历史视为证据，而非背景知识。领域技能用于定义预期机制；当诊断需要正式的图像、时序、资源或回归证明时，使用 $threejs-visual-validation。

维护一份案例记录，包含症状、预期行为、确切环境、最小复现、首个失败的契约、本地证据、上游候选项、固定版本矩阵、结论、操作和限制。未知值记录为未知。

1. 复现确切环境

记录所有可能影响故障的环境事实：解析后的软件包版本、运行时 THREE.REVISION、锁文件解析结果、导入入口、浏览器/操作系统、种子、资源修订版本，以及确切命令或交互。对于渲染或后端相关的主张，还要记录渲染器类、已初始化的后端、GPU 和相关功能。构建仍能复现故障的最小确定性复现。

关于规范 WebGPU 路径的结论，必须使用已初始化且满足 renderer.backend.isWebGPUBackend === true 的 WebGPURenderer。否则，记录该主张受阻的原因；仅当用户明确要求该分支时，才转到 $threejs-compatibility-fallbacks。对于非渲染类 API、导出、资源或版本结论，不要设置渲染器或后端门槛。

当相关环境事实已记录、复现能在该环境下反复失败，并且另一次运行能够区分“已复现”和“未复现”时，此步骤完成。

2. 指明违反的契约和首个故障点

区分 API 语义、数值不变量、渲染状态不变量、资源转换和视觉预期。找出最早失败的断言、帧、通道、绘制、调度、资源转换或诊断信息，而不只是最终症状。

当一个可观测边界划分了最后一个已知正常状态和第一个异常状态时，此步骤完成。

3. 缩减问题，但不要替换机制

移除无关系统，同时保留可疑的 API、材质、几何体路径、后端、投影、精度、所有权和生命周期行为。在跨系统边界处，保留相同的单位、坐标系/原点、所有者、间隔/频率/采样相位、状态标识、有效性/过期状态/错误、重置和完成语义。

不同的渲染器、材质或表示形式可以帮助定位故障，但不能证明原始路径正确。

当每个剩余组件都参与了首次故障，且被怀疑的机制仍是测试对象时，此步骤完成。

4. 核实本地证据

针对解析后的版本，检查已安装的导出映射、源码、类型、测试、示例和迁移资料。优先测试本地假设：应用使用不当、导入过期或重复、迁移变更、渲染器未初始化、后端/功能不受支持、数据无效、输出重复转换、生命周期/同步错误，以及第三方集成。

当每个合理的本地假设都有可执行的结果或明确的缺失证据记录时，此步骤完成。

5. 有条件地调查上游

仅当本地证据无法确定原因、已安装源码与当前文档不一致、可能存在依赖版本的回归或升级问题，或用户询问已知问题时，才调查上游。搜索前请阅读 上游调查，并遵循其中的主要来源顺序。

分别对每个候选问题进行分类：

分类	所需证据
usage-or-integration-error	已安装版本的约定能解释故障，且本地修正通过验证
intentional-api-change	官方迁移说明或源码历史证明这是有意变更
upstream-active	当前检查的代码可复现问题，且有匹配的上游记录
fixed-unreleased	匹配的修复已合并，且检查过的发布记录／程序包内容表明，截至记录的检查时间，该修复尚未发布
fixed-released	已发布的程序包包含该修复，且相同的复现测试通过
not-reproduced	候选配置无法复现本地故障
unrelated	API、后端、症状、受影响范围或复现情况存在实质性差异
insufficient-evidence	缺少复现、遏制、修复或发布证明

已关闭不是一种分类，已合并也不能证明 npm 发布版本包含该修复。无法访问注册表、未检查程序包或发布状态未知，都应归为 insufficient-evidence，而不是 fixed-unreleased。对于发布情况的判断，请记录检查时间和检查过的版本。候选配置测试通过，并不能证明原始故障已解决，除非复现条件和相关环境仍然具有可比性。

检查过的每个候选问题都有且仅有一个有证据支持的分类时，本步骤即告完成。

6. 在依赖版本的情况下保持版本矩阵一致

当诊断取决于版本行为时，每次只更改一个 Three.js 版本，同时保持复现步骤、后端、浏览器／GPU、导入项、资源和断言不变。在证据允许的情况下，记录已安装版本、最后一个已知正常版本、第一个异常版本、修复提交、首个已发布的修复版本，以及当前检查的发布版本。

当有关受影响范围或发布情况的每项结论都基于可比较的行，而非版本标签时，本步骤即告完成。

7. 先遏制并验证，再选择一项措施

首先找出能够保护被违反不变量的最小范围遏制方案。然后在原始复现条件下验证拟议的修正。只有在证明了修复提交、包含该修复的首个已发布程序包，以及该程序包上的复现测试通过后，才建议升级。

选择一项措施：

• 针对误用或无效状态修复应用；
• 升级到经验证包含已发布修复的版本；
• 采用有明确适用范围和移除条件的有限变通方案或版本锁定；
• 当前检查的代码可复现问题且没有匹配案例时，提交上游报告；
• 缺少必要证据时，列为阻碍项。

当选定的措施有通过验证或可证伪的验证方式，注明其版本／后端适用范围和副作用，且没有超出证据支持的结论时，本步骤即告完成。

报告并停止

返回根本原因、已安装版本的结果、相关的上游 issue／PR 和修复提交、受影响范围、首个已发布的修复版本、分类、修复版本的验证结果、回归断言、一项决策以及限制。

当有一个结论得到直接的本地证据支持，并且在涉及上游时也得到直接的一手来源／发布证明时，即可停止。若所有合理的候选问题均已分类，且明确指出了确切缺失的证据，也可停止。措施确定后，不要收集无关的 issue ID。