让我在小程序里做3D，这事儿一开始听着就有点拧巴。小程序那套双线程模型，连DOM都是模拟的，更别说WebGL了。但架不住业务需求往这儿走——商城要展示商品、活动页要搞炫酷入场、数据可视化要立体化。我最早是在H5里折腾Three.js，后来被拉到小程序项目里，要求在微信里跑通一个带交互的3D场景，而且要顺滑得像原生应用，才认认真真把这条链路从踩坑到落地整个捋了一遍。
这篇文章就指望用我实际趟过的路子，帮你把“小程序 + Three.js + gsap”这个组合从开发环境搭建、技术选型原理、核心动画交互到性能调优、线上避坑，每一环都拆开揉碎来讲。如果你正准备在微信小程序里上3D能力，或者已经折腾几天发现各种奇葩报错，这篇应该能让你少走很多弯路。
1. 为什么要在小程序里做3D，以及技术方案的取舍
1.1 小程序里搞3D，跟H5和App有什么本质区别
我们先说结论：小程序不是浏览器。它的渲染层跑在WebView里，但逻辑层走的是JSCore（iOS）或V8（Android），两套线程之间用消息通道通信。这意味着你在页面上能感知到的所有东西，要么是原生组件，要么是被WebView解析的WXML和WXSS。传统H5里，一个Canvas标签往页面上一放，拿JavaScript直接操作上下文就能绘制，但小程序里可以这么做，但性能边界完全不同——尤其是动态重绘、GPU加速、离屏渲染这些在浏览器里很常规的能力，在小程序里都会有额外的损耗和限制。
我最开始做的方案，是在小程序里直接引Three.js渲染到一个<canvas type="webgl">上，然后用wx.createSelectorQuery()拿到节点去初始化场景。这条路确实能跑，但前提是你的3D场景要“轻”——比如展示一个带自转的产品模型、一个粒子背景。一旦场景里模型面数上来、材质复杂了，WebView端帧率就会肉眼可见地掉。原因不复杂：小程序里的WebView和逻辑层通信是异步的，而Three.js每一帧不仅要跑JS计算，还要和逻辑层来回同步状态，性能瓶颈很快就出来了。
另一个方案是走web-view组件，把3D页面整个用H5承载。这个思路在小程序和H5能力并存时比较省事，但问题也很明显：你需要一个独立部署的前端工程，而且web-view的交互、路由、分享都跟小程序本身的生态不能深度打通。比如“从H5页面跳小程序页面”“在H5里拉起支付”这类需求，体验就特别割裂。所以到底用哪条路，取决于你要做的3D到底是“核心功能”还是“锦上添花”。
1.2 Three.js和gsap在一起，解决的是哪两类问题
Three.js管的是“怎么把3D世界画出来”。从数学意义上讲，它封装了场景图、相机、几何体、材质、灯光，以及背后一整套矩阵变换和投影流程。你把一个模型丢进去，它就知道该用哪个视角、什么光源、怎样的贴图来绘制到画布上。但Three.js管不了“怎么让画面动起来像设计稿那样优雅”。
gsap管的就是“时间”这一层。它是一个极其灵活的动画引擎，可以用一行gsap.to()去改变任意对象的任意属性，自带缓动曲线、时间线编排、回调机制，而且它对“属性插值”这件事做到了近乎极致的泛化——只要是JavaScript对象上的某个数字属性，它都能丝滑地补间动画。你会发现，把gsap和Three.js结合，本质上是把3D世界的渲染循环拆成两个层面：Three.js负责“每一帧画什么”，gsap负责“两个时间点之间，模型的旋转角、相机位置、材质透明度应该插值到哪个值”。
所以技术方案的核心逻辑就是：Three.js给出一个稳定的渲染环境，gsap在这个环境之上建立一套时间驱动的动画控制系统。你把gsap挂在Three.js的requestAnimationFrame回调里，每次刷新先让gsap更新当前时刻的所有补间状态，再把更新后的参数喂给Three.js去绘制。这样代码组织起来非常清晰，后面接需求、改交互也容易。
1.3 为什么不是css动画、不是canvas逐帧手写
小程序里有几种动画方案，各自有适用场景。CSS动画只适合对WXML节点做位移、旋转、透明度，它根本不认识3D世界里的相机、模型顶点，所以一开始就被排除。手写canvas逐帧听起来灵活，但你要自己管状态缓存、插值函数、缓动算法、动画队列，基本是重复造轮子，而且代码很容易变成一坨没法维护的状态堆积。
gsap的优势在于，它的Timeline可以让你像剪视频一样编排动画顺序，多个补间之间可以用position参数控制重叠或顺序，还能随时pause()、resume()、reverse()。这套能力拿来做3D场景里的镜头调度和模型入场编排，比手写一套状态机靠谱得多。实测下来，我用gsap在微信开发者工具和真机上做3D动画，只要搞定了渲染层的适配，动画本身的流畅度是完全OK的。
2. 开发环境搭建：从小程序项目初始化到引入Three.js和gsap
2.1 一个能跑的小程序项目，该怎么初始化
搭建这块我们得快进，但有几个关键点得提醒你。小程序项目至少要有app.js、app.json、pages/index/index.js等文件。如果你想跳过微信官方原生开发的繁琐配置，也可以用uni-app或Taro这类跨端框架来做，但这里我们基于原生小程序来讲，因为逻辑最直接，碰到问题也容易排查。
第一步，在微信开发者工具里新建一个小程序项目，AppID建议填上自己注册的测试号，或者干脆用测试号（游客模式会有一些设备能力的限制）。项目目录结构最好单独建一个libs目录用来放第三方库，这样主包体积可控，后面做分包加载也方便。
第二步，确定你的小程序基础库版本。Three.js和gsap对ES6语法的兼容性都很好，但微信开发者工具的“ES6转ES5”选项最好开着，以兼容Android端某些低版本WebView。同时，canvas的type="webgl"参数需要基础库版本在2.9.0以上才稳定支持，建议直接把基础库设到当前最新稳定版本——太老的基础库会导致WebGL上下文创建失败或API缺失。
2.2 引入Three.js的正确姿势，版本选择有讲究
Three.js版本迭代很快，API变化也比较大。我们在小程序里做开发，最重要的不是追新，而是稳。我自己用的版本是three@0.125.0左右，这个版本对模块化支持友好，而且很多互联网上流行的小程序适配教程都是基于这个版本段写的，遇到问题时资料好找。
引入方式有两种。一种是直接把three.min.js的UMD包下载下来，放在libs/three目录下，在页面文件里通过const THREE = require('../../libs/three.min.js')引入。这种方式简单粗暴，但整个包打进去可能接近600KB，对小程序主包体积压力很大。另一种是走npm安装，用npm i three@0.125.0，然后在开发者工具里执行“工具 -> 构建npm”，再在JS里import * as THREE from 'three'。这种方式能在构建时做Tree Shaking，只打包你用到的模块，体积会小很多。
提示：如果你所在的团队没有启用npm构建能力，或者构建npm后出现“未找到npm模块”的报错，建议直接走UMD本地文件方案。微型3D场景用UMD不会产生质的性能影响，但省了很多构建上的折腾。
2.3 gsap在小程序里的集成方式和版本选择
gsap的集成相对简单，它本身不依赖DOM，核心包就一小段JS逻辑，在小程序里直接引用完全没问题。我用的是gsap@3.x版本，这个版本支持ES Module和UMD两种模式。
如果你是从npm安装，可以在app.js里做一个全局挂载：
const gsap = require('gsap'); App({ globalData: { gsap: gsap } });这样所有页面都能通过getApp().globalData.gsap拿到同一个动画引擎实例。或者你也可以在页面内部require，这样每个页面独立使用，方便销毁。我的建议是：如果3D场景只在少数页面出现，就在页面内部引入，避免不必要的全局状态污染。
gsap的核心库默认包含gsap.to/from/fromTo/set这些常用方法，如果你需要时间线编排，还需要额外引入TimelineMax（在gsap 3.x里，gsap.timeline()是内置的，不用额外引）。在3.x版本，gsap.timeline()直接是核心功能，这点和2.x版本有点差别，别搞混了。
3. 核心细节：三步学会用Three.js渲染3D场景
3.1 在Canvas上创建WebGL上下文，这一步深坑最多
小程序里的<canvas>标签和H5有个明显区别：它不是一个即时可见的DOM节点穿越到WebGL，而是需要通过wx.createSelectorQuery()去精确查询节点信息，然后初始化。很多第一次接触的人都会卡在这一步，因为这涉及到小程序“逻辑层和渲染层分离”的问题——JS里拿不到真正的Canvas DOM对象，拿到的是一堆封装后的属性。
基础写法如下：
<canvas type="webgl" id="myCanvas" class="canvas-3d"></canvas>const query = wx.createSelectorQuery(); query.select('#myCanvas') .fields({ node: true, size: true }) .exec((res) => { const canvas = res[0].node; const width = res[0].width; const height = res[0].height; const renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true, alpha: true }); renderer.setPixelRatio(wx.getSystemInfoSync().pixelRatio); renderer.setSize(width, height); });有一个细节至关重要：在真机上，wx.createSelectorQuery()拿到的canvas节点，在小程序基础库版本不同时，可能不是标准的WebGL上下文。如果你遇到getContext返回null，或者画面全黑，十有八九是Canvas类型不匹配或者大小查询过早。我的做法是，在onReady里且wx.nextTick之后再执行查询，给渲染层一个充分的时间完成节点挂载。
3.2 场景、相机、几何体、材质——最小3D世界的组装逻辑
一个能看到的Three.js场景至少需要四样东西：场景Scene、相机Camera、几何体Geometry、材质Material。几何体和材质组合起来叫“网格Mesh”，把Mesh装进Scene，再用Camera从某个视角去看，最后Renderer渲染出来，你才在屏幕上看到了一个3D“物件”。
这一步可以用一个最简单的旋转方块来演示：
// 创建场景 const scene = new THREE.Scene(); // 创建透视相机：视角、宽高比、近裁剪面、远裁剪面 const camera = new THREE.PerspectiveCamera( 45, width / height, 0.1, 1000 ); camera.position.set(0, 1, 5); camera.lookAt(0, 0, 0); // 灯光：没有灯光，物体就是黑的 const ambientLight = new THREE.AmbientLight(0xffffff, 0.6); scene.add(ambientLight); const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8); directionalLight.position.set(5, 10, 7); scene.add(directionalLight); // 几何体 + 材质 -> 网格 const geometry = new THREE.BoxGeometry(1, 1, 1); const material = new THREE.MeshStandardMaterial({ color: 0x4a90d9 }); const cube = new THREE.Mesh(geometry, material); scene.add(cube);这里要特别说明相机参数。透视相机有4个关键参数，前两个（FOV和宽高比）决定了你看到的视野范围有没有拉伸变形，后两个（近裁剪面和远裁剪面）决定了深度渲染精度。相机近了会穿模、远了会闪烁（Z-fighting），在小程序WebView里尽量把物体的尺寸控制在合理范围，不要用极端的0.01作为near值，否则容易在真机上出现深度精度问题。
3.3 驱动渲染循环，OnFrameUpdate的写法要点
Three.js动画的核心是一个持续运行的“渲染循环”。H5里最常见的是requestAnimationFrame，但小程序里注意：你的渲染循环应该挂在Canvas节点对应的requestAnimationFrame上，而不是全局的window.requestAnimationFrame（小程序里根本没有window）。
在小程序里，代码是这样写的：
const renderer = new THREE.WebGLRenderer({ canvas: canvas }); let frameId = null; const renderLoop = () => { // 更新动画状态 cube.rotation.x += 0.01; cube.rotation.y += 0.01; // 渲染当前帧 renderer.render(scene, camera); // 请求下一帧 frameId = canvas.requestAnimationFrame(renderLoop); }; // 启动渲染 frameId = canvas.requestAnimationFrame(renderLoop); // 页面卸载时取消 onUnload() { if (frameId) { canvas.cancelAnimationFrame(frameId); } }注意：这里使用的是canvas.requestAnimationFrame，否则很可能出现“requestAnimationFrame is not a function”的报错。这个API是Canvas节点自带的，真机和开发者工具都支持。另外，渲染循环里的耗时操作要尽量精简，不要在每帧里去new对象或进行复杂的计算，否则帧率会直接受限。
4. gsap与Three.js的融合：从数学模型到动画交互
4.1 gsap如何操纵3D对象的属性，核心原理讲透
gsap补间动画的本质，就是对JavaScript对象的任意数值属性做插值。Three.js的场景对象（如cube.rotation、camera.position）本质上也是普通的JS对象结构。所以，gsap完全不知道它在动画一个“3D模型”，它只知道自己在一段时间内，把一个对象的某个数值从A点平滑过渡到B点，同时应用一个缓动函数。
例如，要让方块旋转180度、再移动到指定位置：
gsap.to(cube.rotation, { y: Math.PI, duration: 1, ease: 'power2.inOut' }); gsap.to(cube.position, { x: 3, y: 2, z: 1, duration: 1.5, ease: 'back.out(1.5)' });这两行代码，就是在任意时间点计算cube.rotation.y的当前值是多少，然后调用renderer.render()。因为渲染循环在不断运行，每一帧拿到的值都在变，所以你看到的就是动画。
这里有一个特别值得注意的地方：gsap默认的动画对象浅层属性，不能直接补间嵌套对象的内部值，除非用object.property这种字符串路径。比如gsap.to(camera, { 'position.x': 5 })是可以的，但如果你想同时改变position的多个轴，直接传{ position: { x: 1, y: 2 } }在某些版本可能不会按预期插值，稳妥做法是分别写属性路径，或者提前把目标值算好。
4.2 gsap.timeline()做动画编排，解决复杂入场效果
实际项目里，模型入场往往是一套组合拳：镜头先推进，模型旋转出现，同时材质透明度从0变为1，然后粒子系统开始扩散，最后镜头缓移到最终视角。如果用多个独立的gsap.to()去控制，代码会产生“时间耦合”——你很难精确地知道第几个动画在第几秒开始结束，也很难中途整体暂停或倒放。
用gsap.timeline()就能把这一切编排得很优雅：
const tl = gsap.timeline({ delay: 0.2, onComplete: () => { console.log('全部动画执行完成'); } }); tl.to(camera.position, { x: 0, y: 1.5, z: 6, duration: 1, ease: 'power2.inOut' }) .to(cube.rotation, { y: Math.PI * 2, duration: 2, ease: 'power1.inOut' }, '-=0.5') // 和上一个动画重叠0.5秒 .to(cube.material, { opacity: 1, duration: 0.8 }, '-=1.2') .to(camera.position, { x: 2, y: 2, z: 3, duration: 1.5, ease: 'sine.inOut' }, '-=0.3');注意最后一个参数，它代表这个动画在时间线上插入的位置。'-=0.5'的含义是“上一个动画结束前0.5秒开始”，'+=1'代表“上一个动画结束后1秒开始”。掌握了这个参数，时间线编排就用活了。
4.3 让动画可以暂停、继续、重复和反向
用户交互过程中，动画不能“一播到底”。退出页面、点击暂停、需求做“倒放”，这些操作都要靠gsap的实例方法去控制。
pause()：暂停当前动画，所有状态卡在当前插值位置。resume()：从暂停位置继续。kill()：杀死动画，但对象属性会保留在当前值（也可以传参数让属性回到初始状态）。reverse()：反向播放动画，适合“收起面板”这类退出交互。repeat参数：在创建动画时设置repeat: 2或repeat: -1（无限循环）。yoyo参数：让动画在到达终点后往返播放，配合repeat: -1就能实现“呼吸灯”或“循环漂浮”效果。
这些能力在小程序里没有损耗，因为gsap完全跑在JS层。但要注意，gsap实例不会自动销毁，页面卸载时最好tl.kill()掉，否则会有内存泄漏的风险。小程序页面切换频繁，这一点尤其容易踩坑。
5. 实操：从零写一个“3D产品展示”页面，完整代码走一遍
5.1 页面结构设计：Canvas、按钮与手势交互区
我们做一个接近真实需求的产品展示页：一个3D方块产品模型，从底部旋转入场，用户可以通过点击按钮让它切换动态效果；点住并拖动可以转动视角；手机横过来的时候，模型会随陀螺仪微微转动。
WXML结构：
<view class="page-wrapper"> <canvas type="webgl" id="productCanvas" class="product-canvas" bindtouchstart="onTouchStart" bindtouchmove="onTouchMove" bindtouchend="onTouchEnd"> </canvas> <view class="action-bar"> <view class="btn" bindtap="startEntrance">入场动画</view> <view class="btn" bindtap="toggleAutoRotate">自动旋转</view> <view class="btn" bindtap="resetView">重置视角</view> </view> </view>面板样式就不贴全量CSS了，核心是给Canvas设置全屏或固定区域的尺寸。注意：Canvas的CSS尺寸和实际像素尺寸不是一回事，你必须在JS里用res[0].width和res[0].height去设置渲染器大小，否则纹理清晰度和触摸坐标都会出问题。
5.2 页面JS完整实现：初始化、渲染循环和触摸交互
下面这段是我整理过的完整可运行核心代码，去掉了业务细节，保留主干逻辑：
const THREE = require('../../libs/three.min.js'); const gsap = require('../../libs/gsap.min.js'); Page({ data: {}, onReady() { this.initThreeCanvas(); }, initThreeCanvas() { const query = wx.createSelectorQuery(); query.select('#productCanvas') .fields({ node: true, size: true }) .exec((res) => { if (!res || !res[0] || !res[0].node) { console.error('Canvas节点未找到'); return; } const canvas = res[0].node; const width = res[0].width; const height = res[0].height; // 1. 创建渲染器 const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true }); renderer.setPixelRatio(wx.getSystemInfoSync().pixelRatio); renderer.setSize(width, height); renderer.shadowMap.enabled = true; // 2. 场景 const scene = new THREE.Scene(); // 3. 相机 const camera = new THREE.PerspectiveCamera(45, width / height, 0.1, 1000); camera.position.set(0, 1.2, 5); camera.lookAt(0, 0, 0); // 4. 灯光 const ambientLight = new THREE.AmbientLight(0xffffff, 0.5); scene.add(ambientLight); const dirLight = new THREE.DirectionalLight(0xffffff, 0.8); dirLight.position.set(5, 10, 7); scene.add(dirLight); // 5. 产品模型（用一个立方体 + 边缘线框代表） const boxGeometry = new THREE.BoxGeometry(1.2, 1.2, 1.2); const boxMaterial = new THREE.MeshPhongMaterial({ color: 0x6c5ce7, transparent: true, opacity: 0.9, shininess: 100 }); const box = new THREE.Mesh(boxGeometry, boxMaterial); scene.add(box); const edges = new THREE.EdgesGeometry(boxGeometry); const lineMaterial = new THREE.LineBasicMaterial({ color: 0xffffff }); const wireframe = new THREE.LineSegments(edges, lineMaterial); box.add(wireframe); // 6. 触摸交互变量 let isDragging = false; let previousTouchX = 0; let previousTouchY = 0; // 7. 启动动画循环 const renderLoop = () => { if (this.data.autoRotate) { box.rotation.y += 0.005; } renderer.render(scene, camera); canvas.requestAnimationFrame(renderLoop); }; canvas.requestAnimationFrame(renderLoop); // 保存实例，供动画控制使用 this.scene = scene; this.camera = camera; this.box = box; this.renderer = renderer; this.canvas = canvas; }); }, // 入场动画 startEntrance() { if (!this.box) return; // 重置初始状态：透明度为0，位置在下方，无旋转 gsap.set(this.box.material, { opacity: 0 }); gsap.set(this.box.position, { y: -2 }); const tl = gsap.timeline(); tl.to(this.box.material, { opacity: 0.9, duration: 0.6, ease: 'power2.out' }) .to(this.box.position, { y: 0, duration: 0.8, ease: 'back.out(1.5)' }, '-=0.3') .to(this.box.rotation, { y: Math.PI * 2, duration: 1.2, ease: 'power2.inOut' }, '-=0.6'); }, toggleAutoRotate() { this.setData({ autoRotate: !this.data.autoRotate }); }, resetView() { if (!this.camera) return; gsap.to(this.camera.position, { x: 0, y: 1.2, z: 5, duration: 0.8, ease: 'power2.inOut' }); }, onTouchStart(e) { if (!this.canvas) return; const touch = e.touches[0]; this.isDragging = true; this.previousTouchX = touch.clientX; this.previousTouchY = touch.clientY; }, onTouchMove(e) { if (!this.isDragging || !this.box) return; const touch = e.touches[0]; const deltaX = touch.clientX - this.previousTouchX; const deltaY = touch.clientY - this.previousTouchY; this.previousTouchX = touch.clientX; this.previousTouchY = touch.clientY; // 旋转模型：横滑改变绕Y轴角度，纵滑改变绕X轴角度 this.box.rotation.y += deltaX * 0.01; this.box.rotation.x += deltaY * 0.01; }, onTouchEnd() { this.isDragging = false; }, onUnload() { if (this.canvas) { this.canvas.cancelAnimationFrame(this.renderLoopId); } if (this.renderer) { this.renderer.dispose(); } // 别忘了杀掉所有gsap动画 gsap.globalTimeline.clear(); } });5.3 关键细节：触摸坐标与3D坐标的对应关系
这里有个关键认知：触摸事件里的clientX/clientY是CSS像素坐标（在小程序里实际是相对视口的逻辑像素），它和Three.js世界坐标之间是两套体系。我们不能直接拿clientX当作三维坐标去移动模型。
正确处理方式是：把触摸点的位移增量转换成旋转角度的变化量。上面代码里的deltaX * 0.01，本质上是用“每移动1像素转动0.01弧度”的灵敏度把屏幕位移映射成角速度。这个系数可以根据模型大小调整，但大方向是这样——触摸交互改变的是“旋转速度增量”，而不是每帧直接把模型设置到某个绝对坐标。
等到你需要做“拖拽物体到某个轨道”这类更复杂的交互时，就得用射线拾取（Raycaster）去计算真实的3D坐标了。这块本期先不展开，但提醒一句：Raycaster在小程序里的精度表现略逊于H5，尤其是在低端Android机上，拾取范围需要做一点容错处理。
6. 性能调优：从30帧到60帧，小程序3D的优化方向
6.1 渲染压力分解：几何、材质、灯光、像素密度
一个3D场景的帧率，是由渲染管线的各个阶段累加决定的。在小程序里，尤其要关注几何复杂度、材质数量和像素填充率。
几何复杂度：模型面数越高，顶点处理和片段着色越贵，一个小程序页面动辄展示几万面的高模，WebView直接吃不消。我的经验是，小程序3D场景里的模型面数控制在5000面以内比较稳，如果必须在移动端展示高精模型，优先用贴图去做出细节感，而不是真的堆几何体。
材质数量：材质相等于渲染时的“着色程序”，每个不同的材质参数组合会产生独立的着色器变体。所以尽量复用材质，不要为了细微的颜色差异new一堆Material。
灯光数量：每开一盏动态光源，片段着色器要额外计算一次光照模型，非常消耗GPU。小程序3D场景最多用两盏灯，一盏环境光保底、一盏方向光做立体感，足够覆盖绝大多数展示型应用。
像素密度：高分辨率屏幕的默认pixelRatio可能是3，渲染器如果直接按这个值输出，宝贵的GPU算力大量用在了像素填充上。我的做法是，把renderer.setPixelRatio()的值限制在2以内，非2K屏场景甚至限制到1.5，画面差异肉眼基本不可感知，但帧率舒服很多。
6.2 微信小程序特有的内存和CPU优化技巧
小程序页面打开时，WXML节点、Canvas数据栈、JS逻辑状态一起跑在有限的内存空间里。3D场景特别容易触碰内存上限，因为WebGL的纹理、缓冲区对象都在GPU侧占用显存，而小程序对显存管理比较粗放，页面回退时释放不及时就会出现越用越卡。
优化的方法有几条。第一，纹理图片用压缩格式。不要直接加载大尺寸PNG，能上WebP就上WebP，尺寸在保证清晰度的前提下尽量缩小，最好256px或512px级别的贴图就够，不要盲目用1024甚至2048。
第二，及时释放不再用的资源。三维场景里的模型和纹理，如果不显示了，最好从Scene中移除并调用geometry.dispose()、material.dispose()，确保WebGL的GPU资源被明确回收。虽然小程序会兜底清理，但显式的释放能够显著降低峰值占用。
第三，双线程模型的“离屏Canvas”思路。如果数据运算量很大（比如粒子系统、模型顶点级联动画），可以考虑放到Worker线程去计算，再把结果传回渲染层。这属于高阶玩法，我在做大规模粒子场景时会用到，普通项目可以先不做。
6.3 帧率监测：怎么看你的3D页面是否流畅
做性能优化，不能靠眼睛判断。小程序里没有浏览器DevTools的Performance面板，但你可以自己写一个简易帧率统计器。
思路很简单：在渲染循环里记录每秒渲染了多少帧。
let frameCount = 0; let lastTime = Date.now(); let currentFps = 60; const renderLoop = () => { frameCount++; const now = Date.now(); if (now - lastTime >= 1000) { currentFps = frameCount; console.log('当前FPS:', currentFps); frameCount = 0; lastTime = now; } renderer.render(scene, camera); canvas.requestAnimationFrame(renderLoop); };根据我的经验，currentFps稳定在50以上，交互操作基本跟手；低于30，就需要考虑降低像素比、精简模型或者减少动态阴影了。另外，微信开发者工具里的“真机调试”自带帧率曲线面板，线上排查问题多依赖真机调试工具，这一点比浏览器模拟器准确得多。
7. 常见问题与排查技巧，我把踩过的坑都列给你
7.1 “canvas type=webgl”不生效，画面黑屏但无报错
这个问题在模拟器和真机上表现不一样，模拟器可能画得出，真机黑屏。排查步骤很固定：
- 确认基础库版本 >= 2.9.0；
- 确认
<canvas>标签写着type="webgl"，不要漏； - 确认
wx.createSelectorQuery()在onReady里调用，且用wx.nextTick包了一层； - 确认
renderer.setSize()传入的宽高不是0。节点尺寸查询时如果组件还没挂载，返回的就是0，一启动就黑屏。
真机上如果以上都查过还是黑屏，建议在代码里打印canvas.getContext('webgl')，看是否返回WebGL上下文。如果返回null，大概率是渲染层WebGL能力被禁用了，这时看看基础库或系统浏览器内核版本。
7.2 gsap动画不触发，或者动画瞬间跳到结尾
这个坑也很经典。gsap在小程序里正常工作依赖JS对象可枚举属性。如果你动画的目标是cube.rotation，但cube还没初始化完成（异步初始化还没执行完），gsap拿到的就是一个undefined，它不会报错，但动画直接跳过。
解决办法：在调用gsap.to()之前，确保Three.js的对象已经成功创建。我通常会在渲染器初始化完成后，设置一个this.isSceneReady = true，在动画方法里加一个判断：
if (!this.isSceneReady) { console.warn('场景还未初始化完毕'); return; }另外还有一个细节：gsap动画默认处理属性时会读取对象当前值。如果你在创建动画之前，用gsap.set()显式设置过初始值，后续动画的起始点会更可控，不会出现“从上次位置继续”的意外。
7.3 真机滚动页面时3D动画会卡顿或闪烁
小程序页面如果包含可滚动区域，滚动事件和Canvas渲染是并行的。但受双线程模型影响，滚动时逻辑层和渲染层的消息处理会更频繁，导致requestAnimationFrame的节奏被打乱。表现就是3D动画掉帧甚至闪烁。
一个有效手段是在页面开始滚动时暂停3D渲染，滚动结束后再恢复：
onPageScroll() { if (this.canvas) { this.isScrolling = true; if (this._scrollTimer) clearTimeout(this._scrollTimer); this._scrollTimer = setTimeout(() => { this.isScrolling = false; }, 200); } }然后在渲染循环里判断this.isScrolling，为true时直接跳过renderer.render()，但继续请求下一帧。这样可以极大降低滚动时的渲染压力，滚动停止后又立刻恢复画面，观感上几乎无影响。
7.4 小程序动态设置标题和备案备注信息，怎么处理
在整合3D功能的同时，你很可能还得处理小程序后台的一些运营配置。这里顺带说两个在踩坑过程中遇到的高频问题。
“小程序动态设置标题”通常指的是页面wx.setNavigationBarTitle()接口。在3D页面里经常要根据模型或场景切换标题，比如“产品详情”和“场景体验”两种状态。这个接口在页面onShow之后调用最稳：
wx.setNavigationBarTitle({ title: '3D产品展示' });注意：这个接口只能在页面内部使用，配置文件里也可以设置navigationBarTitleText作为默认值。如果动态设置后标题没有变化，记得检查是不是全局配置window里的navigationBarTitleText和页面配置冲突了。
“小程序备案备注信息怎么填”这块，主要是新注册小程序后提交备案时需要按规范填写。在“小程序后台 -> 设置 -> 基本设置”里找到备案入口，按照提示填写主办者信息和小程序服务内容说明。注意事项有两个：一是备注信息要写清楚小程序的核心业务功能，与类目、页面对应；二是如果涉及3D展示、在线交易或其他特殊内容，可能会涉及额外资质的审核，提前准备相关证明材料会加速审核。如果只做简单的产品展示，备注就写“提供3D产品展示与资讯浏览服务”即可。
8. 进阶扩展：如何把小程序的3D能力用得更好
8.1 用Three.js的加载器支持GLTF模型
实际项目里，光靠BoxGeometry肯定是撑不起业务的。Three.js有丰富的加载器，GLTFLoader可以加载美术同学输出的.gltf或.glb模型。在小程序里使用GLTFLoader需要注意：GLTFLoader内部有文件下载逻辑，但在小程序里你需要自己实现wx.downloadFile或wx.request来获取模型文件，再传给解析器。
推荐的流程是：将模型文件打包在小程序资源内（体积不要太大），用wx.getFileSystemManager().readFile读取buffer，再用THREE.BufferGeometryLoader或GLTFLoader解析。如果模型超过1MB，不建议打进主包里，这时候走网络下载加缓存策略会好很多。
8.2 粒子系统与shader材质玩法
当你在小程序里能稳定跑通基础3D场景后，可以尝试用THREE.Points做粒子系统，在很多运营活动里能玩出花来——比如星光背景、粒子汇聚变形字、烟花效果。
粒子的核心是BufferGeometry和PointsMaterial。我们可以在position数组中存放几万个粒子坐标，然后在渲染循环里根据gsap驱动的全局时间或某个属性值变化去更新位置，造成“粒子在动态运动”的视觉错觉。
Shader材质是小程序3D进阶的另一个方向。用THREE.ShaderMaterial可以自定义顶点着色器和片元着色器，去实现模型扭曲、流光、渐变、菲涅尔边缘发光等效果。写shader比普通3D编程门槛高一些，但只要你理解了着色器代码在GPU上每帧运行的基本流程，调试起来会越来越得心应手。微信开发者工具对shader的检查不太友好，建议先在浏览器里调试好，再搬到小程序里运行。
8.3 gsap与“3D相机运镜”结合的场景体验
3D场景里最出效果的不是模型本身，而是镜头运动。同一套模型，镜头架在低角度慢慢仰拍，再切换到俯视推进，立刻会有“大片感”。把gsap的Timeline用起来，编排相机的position和lookAt目标，你就能轻松实现运镜效果。
运镜时注意，相机在移动过程中，如果lookAt的目标是动态变化的对象（比如模型在自转或位移动画），你需要确保每帧更新camera的朝向。可以在渲染循环里加一句camera.lookAt(this.targetObject.position)，这样镜头就会始终盯着目标。gsap只用去改camera.position，不操心朝向，画面非常自然。
电源限制方面，运镜动画用的时间线如果长达数秒，要注意在小程序页面切后台时自动暂停。小程序没有visibilitychange事件，但可以在onHide里暂停时间线，在onShow里恢复。我处理过的几个项目里，页面切后台再回来后动画superposition错位的问题，基本都是因为忘记了在onHide时暂停gsap。
9. 小程序3D动画的日常经验沉淀
前面聊了不少具体技术操作，最后沉淀几条我在多个项目里反复验证过的经验心得，这些东西通常不写进文档，但对实际开发进度影响很大。
第一个体会：小程序3D项目的排期，一定要比纯H5项目多预留至少30%的时间做真机适配。开发者工具里的表现和真机差异非常大，低端Android机上的WebGL性能和iOS差距可能高达好几倍。同样是粒子系统，iOS上跑60帧的，Android千元机上可能只有20帧。最靠谱的做法是，项目初期就锁定至少两台低端真机作为基准测试设备，每个迭代版本都跑一遍帧率曲线。
第二个体会：动效设计要克制。3D动画很吸睛，但过度使用会让用户觉得页面花哨、耗电、卡顿。我见过一些需求方希望“入场要炫、旋转要花哨、退出要留余韵”，实际做完，页面主信息反而被遮住了。更好的设计方式是：3D动画服务核心转化目标，入场0.8秒完成主体呈现，交互时按需转动，不搞持续无限循环动画，除非你是特意要做一个背景氛围效果。
第三个体会：把Three.js和gsap的学习成本拆开看。gsap相对简单，掌握to/from/timeline的核心API，绝大部分动画需求就够了。Three.js则琐碎得多，从坐标系、四元数、矩阵、纹理到材质，没有几个月实战很难形成体系。如果你团队里没有人懂WebGL基础，建议先拿官方示例边改边学，不要一上来就搞复杂模型导入和着色器。小程序3D这条路，学习成本和工程成本都不低，但一旦基础底座打通，后面再往上叠需求，速度会上来很快。
第四个体会：团队协作时，3D模块最好独立成组件。在原生小程序里，可以做成自定义组件<three-view>，内部封装Canvas初始化、渲染循环、gsap控制、资源释放逻辑。页面层只需要直接传入模型配置、动画配置和用户交互回调，业务代码不会耦合到Three.js细节。这样后面不管是要做8个3D场景还是换设计稿，都只是增删配置项的问题，不用在每个页面重写一套初始化代码。
最后再分享一个调试小技巧：小程序里3D场景最难的不是“写出来”，而是“看不见哪里出错了”。Three.js报错有时候在真机上根本显示不完整。我习惯在开发阶段给页面加一个人为的“调试面板”，把当前FPS、相机位置、模型旋转角、gsap动画状态实时打印在一块<view>上。这样你在真机上晃动手机、触摸屏幕时，能立刻看到数值变化，快速定位是渲染问题还是动画逻辑问题。等上线前再把这个调试面板通过一个debug字段隐藏掉就行。
小程序 + Three.js + gsap这条路，走通一次之后，你会发现后面再做类似需求会形成一套完整的“套路”。不管是产品展示、数据可视化还是互动营销，这套组合拳的适用面都相当广。希望这篇文章能帮你把项目里最折腾的那段路直接省掉。
