保姆级教程：在uni-app微信小程序里跑起你的第一个Three.js 3D模型（附避坑清单）
零基础实战：在uni-app微信小程序中集成Three.js 3D模型的完整指南
第一次尝试在微信小程序里展示3D模型时，我遇到了一个令人沮丧的问题——直接从npm安装的Three.js官方包在小程序环境中完全无法运行。控制台不断报出document.createElementNS的错误，这让我意识到小程序的特殊环境需要特别处理。经过多次尝试和踩坑，终于找到了一套可靠的解决方案。本文将带你一步步完成从零开始在小程序中集成Three.js的全过程，并分享那些官方文档没有提及的关键细节。
1. 环境准备与适配包选择
微信小程序的JavaScript运行环境与浏览器存在显著差异，这意味着标准的Three.js库无法直接使用。我们需要寻找专门为小程序适配的Three.js版本。经过对比测试，GitHub上yannliao维护的threejs-example-for-miniprogram是目前最稳定且功能完整的解决方案。
1.1 获取适配版Three.js
首先访问项目仓库：
https://github.com/yannliao/threejs-example-for-miniprogram这个仓库包含三个关键文件：
libs/three.weapp.js- 核心Three.js库的小程序适配版jsm/loaders/GLTFLoader.js- 支持GLB/GLTF格式的模型加载器jsm/controls/OrbitControls.js- 实现模型旋转缩放等交互的控制器
提示：建议直接下载整个仓库的ZIP包而非克隆，因为部分依赖文件可能不在主分支上。
1.2 项目文件结构规划
在uni-app项目中创建合理的目录结构有助于后期维护。推荐方案：
├── src │ ├── utils │ │ └── threejs │ │ ├── three.weapp.js │ │ ├── GLTFLoader.js │ │ └── OrbitControls.js这种结构将Three.js相关文件集中管理，同时避免了与项目其他工具库的混淆。
2. 基础场景搭建
2.1 页面结构与Canvas配置
在uni-app的页面文件中，我们需要设置一个全屏的Canvas元素作为3D渲染的容器：
<template> <view class="container"> <canvas class="scene-canvas" canvas-id="scene" type="webgl" :style="canvasStyle" @touchstart="handleTouchStart" @touchmove="handleTouchMove" @touchend="handleTouchEnd" ></canvas> </view> </template>对应的样式设置确保Canvas充满屏幕：
.scene-canvas { width: 100vw; height: 100vh; display: block; }2.2 初始化Three.js环境
在小程序环境中初始化Three.js需要特殊处理，核心步骤包括：
- 获取设备信息：动态适配不同屏幕尺寸
- 注册Canvas：将小程序Canvas与Three.js绑定
- 创建基础场景：包含相机、光照等基本元素
onReady() { const systemInfo = uni.getSystemInfoSync() this.screenWidth = systemInfo.windowWidth this.screenHeight = systemInfo.windowHeight uni.createSelectorQuery() .select('#scene') .node() .exec((res) => { const canvas = res[0].node THREE.global.registerCanvas('scene', canvas) this.initScene(canvas) }) }3. 3D场景核心元素配置
3.1 相机与光照设置
合理的相机参数和光照配置是呈现3D效果的关键：
| 元素类型 | 推荐配置 | 作用说明 |
|---|---|---|
| 透视相机 | new THREE.PerspectiveCamera(75, width/height, 0.1, 1000) | 模拟人眼视角，适合大多数3D场景 |
| 半球光 | new THREE.HemisphereLight(0xffffff, 0x444444, 1) | 提供环境基础照明 |
| 平行光 | new THREE.DirectionalLight(0xffffff, 0.8) | 产生明确阴影和明暗对比 |
initScene(canvas) { // 创建场景 this.scene = new THREE.Scene() this.scene.background = new THREE.Color(0xf0f0f0) // 设置相机 this.camera = new THREE.PerspectiveCamera( 75, this.screenWidth / this.screenHeight, 0.1, 1000 ) this.camera.position.set(0, 0, 15) // 添加光照 const ambientLight = new THREE.HemisphereLight(0xffffff, 0x444444, 1) ambientLight.position.set(0, 20, 0) this.scene.add(ambientLight) const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8) directionalLight.position.set(0, 0, 20) this.scene.add(directionalLight) }3.2 交互控制器集成
OrbitControls是实现模型交互的核心组件，在小程序环境中需要特别注意：
- 阻尼效果：使操作更流畅
- 移动限制：避免相机位置失控
- 触摸事件绑定：确保移动端手势正常响应
// 初始化控制器 this.controls = new OrbitControls(this.camera, canvas) this.controls.target.set(0, 0, 0) this.controls.enableDamping = true this.controls.dampingFactor = 0.05 this.controls.maxPolarAngle = Math.PI * 0.9 this.controls.minDistance = 5 this.controls.maxDistance = 504. 模型加载与性能优化
4.1 加载网络模型资源
微信小程序安全限制要求所有模型资源必须通过HTTPS协议加载：
const loader = new GLTFLoader() loader.load( 'https://example.com/models/your-model.glb', (gltf) => { const model = gltf.scene model.scale.set(0.5, 0.5, 0.5) model.position.y = -2 this.scene.add(model) this.startRenderLoop() }, undefined, (error) => { console.error('模型加载失败:', error) } )4.2 性能优化要点
在小程序环境中运行3D内容需要特别注意性能问题：
- 模型简化：使用低多边形(Low Poly)模型
- 纹理压缩：推荐使用Basis Universal格式
- 帧率控制：根据设备性能动态调整
- 内存管理：及时销毁不再使用的资源
startRenderLoop() { const render = () => { this.animationId = requestAnimationFrame(render) // 只在控制器激活时更新 if (this.controls.enabled) { this.controls.update() } // 根据设备性能动态调整渲染频率 if (Date.now() - this.lastRenderTime > 16) { this.renderer.render(this.scene, this.camera) this.lastRenderTime = Date.now() } } render() }5. 常见问题解决方案
在实际开发中，我遇到了几个典型问题及解决方法：
控制器无响应：
- 确保正确绑定了touch事件
- 检查
OrbitControls.js中three.weapp.js的导入路径
模型显示异常：
- 确认模型尺寸和位置在合理范围内
- 检查模型法线方向是否正确
内存泄漏：
- 页面卸载时务必取消动画帧
- 手动清理不再使用的纹理和几何体
onUnload() { if (this.animationId) { cancelAnimationFrame(this.animationId) } // 清理Three.js资源 this.scene.traverse((object) => { if (object.geometry) { object.geometry.dispose() } if (object.material) { if (Array.isArray(object.material)) { object.material.forEach(m => m.dispose()) } else { object.material.dispose() } } }) THREE.global.unregisterCanvas('scene') }经过这些步骤，你应该已经能在uni-app开发的小程序中流畅展示3D模型了。记得在真机上测试性能表现，不同Android设备的GPU性能差异可能导致渲染效果大不相同。