网页嵌入 3D 人物实现指南：基于 React 与 Three.js

2. 3D 组件封装

创建 Model.tsx 组件，负责加载模型和处理动画逻辑。

import { Canvas, extend, useFrame } from '@react-three/fiber';
import { OrbitControls, useAnimations, useGLTF } from '@react-three/drei';
import { useEffect } from 'react';
import { agentModel } from '../../utils/model';

// 扩展 Three.js 几何体（如需特殊平面）
import { PlaneGeometry } from 'three';
extend({ PlaneGeometry });

function Model({ url }) {
    // 加载 glTF/GLB 模型
    const { scene, animations } = useGLTF(url);
    
    // 提取动画数据
    const { actions, mixer } = useAnimations(animations, scene);

    useEffect(() => {
        if (actions) {
            // 播放指定名称的动画
            // 注意：动画名称取决于 Mixamo 导出时的命名，通常为 'Armature|mixamo.com|Layer0'
            const actionName = Object.keys(actions)[0];
            if (actionName) {
                actions[actionName].play();
            }
        }
    }, [actions]);

    // 每一帧更新动画混合器
    useFrame((state, delta) => {
        if (mixer) {
            mixer.update(delta);
        }
    });

    return <primitive object={scene} position={[0, -1, 0]} />;
}

export default function AgentModel() {
    return (
        <Canvas
            camera={{ position: [0, 2, 5], fov: 30 }}
            shadows
            style={{ width: '100%', height: '100%' }}
        >
            <OrbitControls enableZoom={false} />
            <ambientLight intensity={0.5} />
            <directionalLight position={[5, 5, 5]} intensity={1} />
            <pointLight position={[-5, 5, -5]} intensity={0.5} />
            <Model url={agentModel} />
        </Canvas>
    );
}

3. 关键参数说明

• Camera Position: [0, 2, 5] 设置摄像机位置，使人物位于画面中心偏下。
• Lights: 组合使用环境光、方向光和点光源，确保模型受光均匀且产生阴影。
• Animation Name: 务必检查 useAnimations 返回的 actions 对象键名，不同来源的模型动画名称可能不同。

步骤五：常见问题与优化

1. 模型显示为白色

这通常是因为贴图路径错误或材质未正确加载。

• 检查 Blender 中是否保留了贴图。
• 确保 .glb 文件中的纹理被正确打包（Embedded Textures）。
• 在 React 中，如果使用本地图片路径，需确保构建工具能解析该路径。

2. 动画不播放

• 检查 actions 对象是否为空。
• 确认动画名称是否正确匹配。
• 确保 mixer.update() 在 useFrame 中被调用。

3. 性能优化

• 模型压缩：使用 Draco 压缩算法减小 .glb 体积。
• LOD (Level of Detail)：远距离时降低模型面数。
• 纹理尺寸：根据屏幕分辨率限制纹理大小（如 1024x1024）。

总结

通过上述步骤，我们成功在 React 网页中嵌入了一个带有动画的 3D 人物。这一方案适用于 AI 对话助手、虚拟导购等多种场景。核心在于利用成熟的工具链（ReadyPlayerMe/Mixamo）生成资产，并通过 React Three Fiber 实现高效的 WebGL 渲染。开发者可根据实际需求调整光照、视角及交互逻辑，打造沉浸式的 Web 3D 体验。