让我在小程序里做3D这事儿一开始听着就有点拧巴。小程序那套双线程模型连DOM都是模拟的更别说WebGL了。但架不住业务需求往这儿走——商城要展示商品、活动页要搞炫酷入场、数据可视化要立体化。我最早是在H5里折腾Three.js后来被拉到小程序项目里要求在微信里跑通一个带交互的3D场景而且要顺滑得像原生应用才认认真真把这条链路从踩坑到落地整个捋了一遍。这篇文章就指望用我实际趟过的路子帮你把“小程序 Three.js gsap”这个组合从开发环境搭建、技术选型原理、核心动画交互到性能调优、线上避坑每一环都拆开揉碎来讲。如果你正准备在微信小程序里上3D能力或者已经折腾几天发现各种奇葩报错这篇应该能让你少走很多弯路。1. 为什么要在小程序里做3D以及技术方案的取舍1.1 小程序里搞3D跟H5和App有什么本质区别我们先说结论小程序不是浏览器。它的渲染层跑在WebView里但逻辑层走的是JSCoreiOS或V8Android两套线程之间用消息通道通信。这意味着你在页面上能感知到的所有东西要么是原生组件要么是被WebView解析的WXML和WXSS。传统H5里一个Canvas标签往页面上一放拿JavaScript直接操作上下文就能绘制但小程序里可以这么做但性能边界完全不同——尤其是动态重绘、GPU加速、离屏渲染这些在浏览器里很常规的能力在小程序里都会有额外的损耗和限制。我最开始做的方案是在小程序里直接引Three.js渲染到一个canvas typewebgl上然后用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和gsap2.1 一个能跑的小程序项目该怎么初始化搭建这块我们得快进但有几个关键点得提醒你。小程序项目至少要有app.js、app.json、pages/index/index.js等文件。如果你想跳过微信官方原生开发的繁琐配置也可以用uni-app或Taro这类跨端框架来做但这里我们基于原生小程序来讲因为逻辑最直接碰到问题也容易排查。第一步在微信开发者工具里新建一个小程序项目AppID建议填上自己注册的测试号或者干脆用测试号游客模式会有一些设备能力的限制。项目目录结构最好单独建一个libs目录用来放第三方库这样主包体积可控后面做分包加载也方便。第二步确定你的小程序基础库版本。Three.js和gsap对ES6语法的兼容性都很好但微信开发者工具的“ES6转ES5”选项最好开着以兼容Android端某些低版本WebView。同时canvas的typewebgl参数需要基础库版本在2.9.0以上才稳定支持建议直接把基础库设到当前最新稳定版本——太老的基础库会导致WebGL上下文创建失败或API缺失。2.2 引入Three.js的正确姿势版本选择有讲究Three.js版本迭代很快API变化也比较大。我们在小程序里做开发最重要的不是追新而是稳。我自己用的版本是three0.125.0左右这个版本对模块化支持友好而且很多互联网上流行的小程序适配教程都是基于这个版本段写的遇到问题时资料好找。引入方式有两种。一种是直接把three.min.js的UMD包下载下来放在libs/three目录下在页面文件里通过const THREE require(../../libs/three.min.js)引入。这种方式简单粗暴但整个包打进去可能接近600KB对小程序主包体积压力很大。另一种是走npm安装用npm i three0.125.0然后在开发者工具里执行“工具 - 构建npm”再在JS里import * as THREE from three。这种方式能在构建时做Tree Shaking只打包你用到的模块体积会小很多。提示如果你所在的团队没有启用npm构建能力或者构建npm后出现“未找到npm模块”的报错建议直接走UMD本地文件方案。微型3D场景用UMD不会产生质的性能影响但省了很多构建上的折腾。2.3 gsap在小程序里的集成方式和版本选择gsap的集成相对简单它本身不依赖DOM核心包就一小段JS逻辑在小程序里直接引用完全没问题。我用的是gsap3.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 typewebgl idmyCanvas classcanvas-3d/canvasconst 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 classpage-wrapper canvas typewebgl idproductCanvas classproduct-canvas bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd /canvas view classaction-bar view classbtn bindtapstartEntrance入场动画/view view classbtn bindtaptoggleAutoRotate自动旋转/view view classbtn bindtapresetView重置视角/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 typewebgl”不生效画面黑屏但无报错这个问题在模拟器和真机上表现不一样模拟器可能画得出真机黑屏。排查步骤很固定确认基础库版本 2.9.0确认canvas标签写着typewebgl不要漏确认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这条路走通一次之后你会发现后面再做类似需求会形成一套完整的“套路”。不管是产品展示、数据可视化还是互动营销这套组合拳的适用面都相当广。希望这篇文章能帮你把项目里最折腾的那段路直接省掉。 小程序3D开发实战：Three.js与gsap动画全流程解析
让我在小程序里做3D这事儿一开始听着就有点拧巴。小程序那套双线程模型连DOM都是模拟的更别说WebGL了。但架不住业务需求往这儿走——商城要展示商品、活动页要搞炫酷入场、数据可视化要立体化。我最早是在H5里折腾Three.js后来被拉到小程序项目里要求在微信里跑通一个带交互的3D场景而且要顺滑得像原生应用才认认真真把这条链路从踩坑到落地整个捋了一遍。这篇文章就指望用我实际趟过的路子帮你把“小程序 Three.js gsap”这个组合从开发环境搭建、技术选型原理、核心动画交互到性能调优、线上避坑每一环都拆开揉碎来讲。如果你正准备在微信小程序里上3D能力或者已经折腾几天发现各种奇葩报错这篇应该能让你少走很多弯路。1. 为什么要在小程序里做3D以及技术方案的取舍1.1 小程序里搞3D跟H5和App有什么本质区别我们先说结论小程序不是浏览器。它的渲染层跑在WebView里但逻辑层走的是JSCoreiOS或V8Android两套线程之间用消息通道通信。这意味着你在页面上能感知到的所有东西要么是原生组件要么是被WebView解析的WXML和WXSS。传统H5里一个Canvas标签往页面上一放拿JavaScript直接操作上下文就能绘制但小程序里可以这么做但性能边界完全不同——尤其是动态重绘、GPU加速、离屏渲染这些在浏览器里很常规的能力在小程序里都会有额外的损耗和限制。我最开始做的方案是在小程序里直接引Three.js渲染到一个canvas typewebgl上然后用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和gsap2.1 一个能跑的小程序项目该怎么初始化搭建这块我们得快进但有几个关键点得提醒你。小程序项目至少要有app.js、app.json、pages/index/index.js等文件。如果你想跳过微信官方原生开发的繁琐配置也可以用uni-app或Taro这类跨端框架来做但这里我们基于原生小程序来讲因为逻辑最直接碰到问题也容易排查。第一步在微信开发者工具里新建一个小程序项目AppID建议填上自己注册的测试号或者干脆用测试号游客模式会有一些设备能力的限制。项目目录结构最好单独建一个libs目录用来放第三方库这样主包体积可控后面做分包加载也方便。第二步确定你的小程序基础库版本。Three.js和gsap对ES6语法的兼容性都很好但微信开发者工具的“ES6转ES5”选项最好开着以兼容Android端某些低版本WebView。同时canvas的typewebgl参数需要基础库版本在2.9.0以上才稳定支持建议直接把基础库设到当前最新稳定版本——太老的基础库会导致WebGL上下文创建失败或API缺失。2.2 引入Three.js的正确姿势版本选择有讲究Three.js版本迭代很快API变化也比较大。我们在小程序里做开发最重要的不是追新而是稳。我自己用的版本是three0.125.0左右这个版本对模块化支持友好而且很多互联网上流行的小程序适配教程都是基于这个版本段写的遇到问题时资料好找。引入方式有两种。一种是直接把three.min.js的UMD包下载下来放在libs/three目录下在页面文件里通过const THREE require(../../libs/three.min.js)引入。这种方式简单粗暴但整个包打进去可能接近600KB对小程序主包体积压力很大。另一种是走npm安装用npm i three0.125.0然后在开发者工具里执行“工具 - 构建npm”再在JS里import * as THREE from three。这种方式能在构建时做Tree Shaking只打包你用到的模块体积会小很多。提示如果你所在的团队没有启用npm构建能力或者构建npm后出现“未找到npm模块”的报错建议直接走UMD本地文件方案。微型3D场景用UMD不会产生质的性能影响但省了很多构建上的折腾。2.3 gsap在小程序里的集成方式和版本选择gsap的集成相对简单它本身不依赖DOM核心包就一小段JS逻辑在小程序里直接引用完全没问题。我用的是gsap3.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 typewebgl idmyCanvas classcanvas-3d/canvasconst 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 classpage-wrapper canvas typewebgl idproductCanvas classproduct-canvas bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd /canvas view classaction-bar view classbtn bindtapstartEntrance入场动画/view view classbtn bindtaptoggleAutoRotate自动旋转/view view classbtn bindtapresetView重置视角/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 typewebgl”不生效画面黑屏但无报错这个问题在模拟器和真机上表现不一样模拟器可能画得出真机黑屏。排查步骤很固定确认基础库版本 2.9.0确认canvas标签写着typewebgl不要漏确认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这条路走通一次之后你会发现后面再做类似需求会形成一套完整的“套路”。不管是产品展示、数据可视化还是互动营销这套组合拳的适用面都相当广。希望这篇文章能帮你把项目里最折腾的那段路直接省掉。