Частые ошибки при работе с 3D

Частые ошибки при работе с 3D

FAQ по типичным проблемам при использовании React Three Fiber, Drei и связанных библиотек в Next.js. Решения основаны на опыте внедрения в проекте.

1. Canvas не отображается / чёрный экран

Причины:

• Контейнер без высоты — Canvas наследует height: 0.
• SSR — R3F не работает на сервере, нужен dynamic с ssr: false.
• WebGL не поддерживается — проверьте в старых браузерах.

Решение:

<div className="h-[400px] w-full">
  <Canvas>...</Canvas>
</div>

И обязательно динамический импорт с ssr: false.

2. «Hydration failed» или ошибки при рендере

Причина: Canvas или компоненты внутри него рендерятся на сервере.

Решение: Убедитесь, что весь 3D-контент в компоненте с "use client" и Canvas загружается через dynamic(..., { ssr: false }).

3. Модели / текстуры не загружаются

Причины:

• CORS при загрузке с другого домена.
• Неверный путь к файлу (GLB, HDR).
• useGLTF / useTexture вызываются до монтирования.

Решение: Размещайте ассеты в public/ и используйте пути вида /models/scene.glb. Для внешних URL настройте CORS на сервере или используйте прокси.

4. Rapier / WASM не инициализируется

Причина: Rapier загружается асинхронно, физика вызывается до await RAPIER.init().

Решение: Оберните сцену с физикой в Suspense и инициализируйте Rapier в useEffect или при первом рендере клиентского компонента.

5. Низкий FPS на мобильных

Причины: Слишком много объектов, сложные тени, высокое разрешение.

Решение:

• Уменьшите количество полигонов и источников света.
• Используйте frameloop="demand" для статичных сцен.
• Отключайте тени на мобильных: shadowMap.enabled = false.

Связанные статьи

• Интеграция R3F в Next.js — настройка проекта
• React Three Fiber (R3F) — основы
• Rapier — физика — физический движок

Дополнительно

• React Three Fiber — Troubleshooting
• Three.js — FAQ