Phaser 3重启场景时触发Cannot read 'cut'/'glTexture'错误求助

错误根源 #

这类空指针错误本质是场景重启流程中，资源销毁不彻底或存在残留引用：

• Canvas模式下的cut报错：Sprite或Texture对象已被销毁，但其内部Canvas纹理引用已置空，后续代码仍尝试调用cut方法。
• WebGL模式下的glTexture报错：WebGL纹理资源已被释放，但有逻辑还在访问其glTexture属性。

常见触发点：

• 全局变量/外部模块持有场景内对象的引用，导致Phaser无法彻底销毁资源。
• 自定义精灵、物理组件未在destroy方法中正确清理内部资源或事件监听。
• 场景的shutdown/destroy生命周期函数遗漏了资源销毁步骤。

修复步骤 #

1. 完善场景销毁逻辑 #

在场景的shutdown方法中手动清理所有自定义对象，确保引用被清空：

shutdown() {
  // 销毁玩家并清空引用
  if (this.player) {
    this.player.destroy(true);
    this.player = null;
  }
  // 清理敌人组
  if (this.enemies) {
    this.enemies.clear(true, true);
    this.enemies = null;
  }
  // 调用父类方法完成默认销毁流程
  super.shutdown();
}

2. 杜绝外部残留引用 #

不要用全局变量或非场景内模块保存场景对象（如Sprite、Texture），所有对象引用都应封装在场景类内部，随场景销毁自动释放。

3. 修复自定义组件的销毁逻辑 #

如果使用了自定义精灵或组件，确保destroy方法正确清理资源：

class Player extends Phaser.GameObjects.Sprite {
  destroy(fromScene) {
    // 移除自定义事件监听
    this.off('animationcomplete', this.handleAnimEnd, this);
    // 销毁物理体
    this.body?.destroy();
    // 调用父类销毁方法
    super.destroy(fromScene);
  }
}

4. 延迟重启（临时 workaround） #

若暂时定位不到泄漏点，可通过延迟执行重启确保销毁流程完成：

// 替换直接调用this.scene.restart()
setTimeout(() => this.scene.restart(), 100);

5. 升级Phaser版本 #

旧版本Phaser可能存在资源清理的bug，建议升级到最新稳定版（如3.80.x），许多此类问题已被官方修复。

内容的提问来源于stack exchange，提问作者Owen Greenhalgh