Next.js14中@react-three/fiber的JSX内置元素未被TypeScript识别

问题 #

我正在使用Next.js 14、TypeScript、Tailwind和@react-three/fiber构建项目以加载3D模型，但持续遇到TypeScript错误，提示directionalLight、ambientLight、primitive等Three.js元素在JSX中不被识别。

环境配置 #

• Next.js: 14.2.16
• React: 19.0.0
• @react-three/fiber: 8.17.14
• @react-three/drei: 9.121.4
• Three.js: 0.173.0
• TypeScript: 5.x

报错代码 #

"use client";

import { Canvas } from "@react-three/fiber";
import { Suspense } from "react";
import { OrbitControls, useGLTF } from "@react-three/drei";

export default function Avatar() {
  const { scene } = useGLTF("/models/avatar.glb");

  return (
    <Canvas camera={{ position: [0, 1, 3], fov: 50 }} className="w-full h-full">
      <Suspense fallback={null}>
        <ambientLight intensity={0.5} />
        <directionalLight position={[2, 2, 2]} intensity={1} />
        <primitive object={scene} scale={1.5} />
        <OrbitControls />
      </Suspense>
    </Canvas>
  );
}

TypeScript错误信息 #

Property 'directionalLight' does not exist on type 'JSX.IntrinsicElements'.
Property 'ambientLight' does not exist on type 'JSX.IntrinsicElements'.
Property 'primitive' does not exist on type 'JSX.IntrinsicElements'.

已尝试的解决方法 #

• 将Next.js从15降级到14
• 添加global.d.ts文件：

import * as THREE from "three";
declare module "@react-three/fiber" {
interface ThreeElements {
primitive: { object: THREE.Object3D };
}
}

• 重启Next.js服务（npm run dev）

问题仍未解决，需找到在Next.js 14中正确使用@react-three/fiber组件且消除TypeScript错误的方法。

期望效果：

• ambientLight、directionalLight和primitive不再出现TypeScript错误
• 3D模型能在场景中正确加载

解决方案 #

1. 修正类型声明文件 #

你之前的global.d.ts写法有误，正确的做法是扩展React的JSX.IntrinsicElements以包含@react-three/fiber的类型。在项目根目录或src/types下创建/修改类型声明文件（如global.d.ts）：

import * as THREE from 'three';
import type { ThreeElements } from '@react-three/fiber';

declare global {
  namespace JSX {
    interface IntrinsicElements extends ThreeElements {}
  }
}

2. 调整tsconfig.json配置 #

确保TypeScript能识别你的类型声明文件，在tsconfig.json中添加以下配置：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "include": ["src/**/*", "global.d.ts"],
    "jsx": "preserve"
  }
}

如果类型声明文件在src/types目录下，需对应调整include路径。

3. 降级React到稳定版 #

React 19为测试版本，可能与@react-three/fiber存在兼容性问题，建议降级到React 18：

npm install react@18 react-dom@18

4. 重启服务与TS语言服务器 #

修改配置后，重启Next.js服务：

npm run dev

同时重启编辑器的TypeScript语言服务（如VS Code按Ctrl+Shift+P，选择"TypeScript: Restart TS Server"），确保类型更新生效。

5. 显式导入组件（替代方案） #

若上述方法无效，可直接导入@react-three/fiber提供的大写组件，跳过全局类型扩展：

"use client";

import { Canvas, AmbientLight, DirectionalLight, Primitive } from "@react-three/fiber";
import { Suspense } from "react";
import { OrbitControls, useGLTF } from "@react-three/drei";

export default function Avatar() {
  const { scene } = useGLTF("/models/avatar.glb");

  return (
    <Canvas camera={{ position: [0, 1, 3], fov: 50 }} className="w-full h-full">
      <Suspense fallback={null}>
        <AmbientLight intensity={0.5} />
        <DirectionalLight position={[2, 2, 2]} intensity={1} />
        <Primitive object={scene} scale={1.5} />
        <OrbitControls />
      </Suspense>
    </Canvas>
  );
}

内容的提问来源于stack exchange，提问作者raiyan khan