graphics-troubleshooting（图形故障排除）

Graphics Troubleshooting

Diagnose and fix 3D web graphics issues fast. Organized by symptom (what you see) for rapid diagnosis.

Library Versions (2026) - Three.js: r171+ - React Three Fiber: v9.5+ - @react-three/drei: v9.116+ - @react-three/rapier: v2+

Quick Diagnosis

Nothing Renders (Black/Empty Screen)

R3F Minimum Visible Scene:

<Canvas>
  <ambientLight intensity={0.5} />
  <directionalLight position={[5, 5, 5]} />
  <mesh position={[0, 0, 0]}>
    <boxGeometry />
    <meshStandardMaterial color="red" />
  </mesh>
</Canvas>

Vanilla Three.js Minimum Scene:

import * as THREE from 'three/webgpu'

const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
camera.position.z = 5

const renderer = new THREE.WebGPURenderer({ antialias: true })
await renderer.init()
renderer.setSize(window.innerWidth, window.innerHeight)
document.body.appendChild(renderer.domElement)

// Add light - required for Standard materials
scene.add(new THREE.AmbientLight(0xffffff, 0.5))
scene.add(new THREE.DirectionalLight(0xffffff, 1))

// Add visible object
const mesh = new THREE.Mesh(
  new THREE.BoxGeometry(),
  new THREE.MeshStandardMaterial({ color: 'red' })
)
scene.add(mesh)

function animate() {
  renderer.render(scene, camera)
}
renderer.setAnimationLoop(animate)

Object Renders But Looks Wrong

Performance Issues

Quick Performance Check:

// Add to console or scene
console.log('Draw calls:', renderer.info.render.calls)
console.log('Triangles:', renderer.info.render.triangles)
console.log('Geometries:', renderer.info.memory.geometries)
console.log('Textures:', renderer.info.memory.textures)

See references/performance.md for detailed profiling.

Loading Failures

Loader Setup Pattern:

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js'
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js'

const loader = new GLTFLoader()

// Draco (for Draco-compressed models)
const dracoLoader = new DRACOLoader()
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/')
loader.setDRACOLoader(dracoLoader)

// Meshopt (for Meshopt-compressed models)
loader.setMeshoptDecoder(MeshoptDecoder)

// KTX2 (for Basis Universal textures)
const ktx2Loader = new KTX2Loader()
ktx2Loader.setTranscoderPath('https://cdn.jsdelivr.net/npm/three@0.171.0/examples/jsm/libs/basis/')
ktx2Loader.detectSupport(renderer)
loader.setKTX2Loader(ktx2Loader)

See references/loading.md for more patterns.

Physics Issues (@react-three/rapier)

Minimum Physics Setup:

import { Physics, RigidBody } from '@react-three/rapier'

<Physics gravity={[0, -9.81, 0]} debug>
  {/* Ground - fixed, doesn't move */}
  <RigidBody type="fixed">
    <mesh position={[0, -1, 0]}>
      <boxGeometry args={[10, 0.5, 10]} />
      <meshStandardMaterial />
    </mesh>
  </RigidBody>

  {/* Falling object - dynamic */}
  <RigidBody type="dynamic">
    <mesh>
      <sphereGeometry />
      <meshStandardMaterial />
    </mesh>
  </RigidBody>
</Physics>

Shader/Material Errors

TSL Debug Pattern:

import { color, uniform } from 'three/tsl'

// Start simple, add complexity
const material = new THREE.MeshBasicNodeMaterial()
material.colorNode = color(0xff0000) // Should be red

// If this works, add your custom logic incrementally

Related Skills

Reference Files

• references/visual-bugs.md - Z-fighting, clipping, shadow artifacts, transparency issues
• references/performance.md - Profiling, optimization, memory management
• references/loading.md - Asset loading, decoder setup, CORS, caching