简介一份面向微信小程序开发者的3D集成示例工程基于three.js解决在小程序中加载外部3D模型的核心问题。开发者可以从中掌握如何通过wx.createScriptModule加载three.js库、初始化场景与渲染器、使用OBJLoader加载OBJ/FBX等模型并了解动画循环、触摸交互和LOD性能优化等关键实践经验同时掌握基础排错思路。压缩包内含11个文件、总大小167KB其中4个js文件负责3D场景与加载逻辑4个json文件为项目配置wxml/wxss定义页面结构样式md提供说明文档整体结构简洁清晰便于快速对照上手。目前已有3205人学习下载。这份示例工程特别适合希望在小程序中引入3D体验、但缺乏完整集成路径参考的初中级前端开发者直接运行示例或阅读源码即可复现基础流程为后续扩展手势控制、模型切换等交互功能打下扎实基础。1. 小程序加载外部 3D 模型先说结论再谈坑做小程序商城的时候接过一个商品 3D 展示需求想着直接把网页版 Three.js 的 demo 搬进去结果白屏一整天。后来才明白小程序没有 window、没有 DOM、没有 XMLHttpRequest官方 Three.js 在小程序里根本跑不起来需要一套专门的适配运行时。这套资源解决的就是「在微信小程序里加载外部 glTF/GLB 模型并完成交互」这件事适合需要在小程序里做 3D 展示、产品预览、数字藏品展示的开发者。核心语言是 JavaScript底层渲染依赖 WebGL但工程链路与浏览器版差异很大先讲清楚差异再动手能省很多时间。2. 选型与原理为什么是 Three.js 适配方案以及小程序 3D 的边界小程序端的 3D 方案不止一种有纯 Canvas 2D 自己画线框的、有 WebGL 手写矩阵的、也有用适配版 Three.js 的。绝大多数成型的项目都选适配版 Three.js 运行时因为它把场景图、相机、灯光、材质、加载器这些基础能力都带过来了你不用从零处理矩阵和渲染管线。2.1 小程序 3D 渲染的底层差异从 Canvas 节点到 WebGL 上下文浏览器里创建一个 WebGL 渲染器拿到的 canvas 是一个 HTMLCanvasElement自带 getContext(webgl)。小程序里canvas 是 WXML 里的一个组件节点需要通过wx.createSelectorQuery拿到节点对象而且不同基础库版本暴露的节点结构不一样。2D canvas 节点和 webgl 上下文之间要做一层桥接适配运行时做的事情之一就是把这层桥接打通。const query wx.createSelectorQuery() query.select(#gl-canvas).fields({ node: true, size: true }).exec((res) { const canvas res[0].node const width res[0].width const height res[0].height console.log(canvas node ready, canvas, width, height) })这段代码是获取 canvas 节点的标准姿势。fields({ node: true, size: true })里的node: true表示要返回真实的节点对象size: true表示同时返回节点的宽高。exec的回调会在查询完成后触发注意这里的width和height是样式尺寸并不等于 canvas 的内部像素尺寸后面创建渲染器时还需要单独设置。一个常见误用是把查询放到onLoad里执行。小程序页面的onLoad阶段 WXML 还没有完成渲染选择器查不到节点回调不会触发。我第一次就是这个原因白屏后来改成在onReady里做才正常。适配版运行时对这个过程的封装程度不同有的会直接帮你查节点有的需要你传入 canvas 再自己初始化这套资源里的示例是后者可控性更强。2.2 适配版运行时如何补齐缺失 API以 XMLHttpRequest 和 DOM 为关键Three.js 官方源码里很多模块依赖浏览器 API。TextureLoader加载图片时用new Image()FileLoader加载模型时用new XMLHttpRequest()场景里的对象还依赖document全局对象做事件分发。小程序里这些统统不存在直接引入官方包会在初始化阶段就抛window is not defined。适配版运行时做的是「作用域注入」把整个 Three.js 源码包在一个函数里调用时传入一个自定义的canvas对象再提供一个阉割版的window、document别名把Image替换成小程序的canvas.createImage()把 XMLHttpRequest 替换成基于wx.request或文件系统读写的自定义实现。这个过程对业务代码几乎是透明的但不透明的地方在于加载器。浏览器全局对象浏览器里的行为小程序替换方案window全局作用域与事件注册适配运行时注入的代理对象document创建元素、绑定事件、查询节点canvas 节点加事件监听XMLHttpRequest发起的网络请求加载模型/bin/纹理wx.request 或 FileSystemManager 读取Image解码图片为纹理canvas.createImage 或 wx.getImageInfo这张表是排查问题的关键地图。凡是模型加载失败、纹理不显示、事件不响应的报错信息追到根因几乎都能落回某一行的适配差异上。我在项目中遇到过GLTFLoader内部调用了URL.createObjectURL的情况因为适配运行时没有实现这个 API导致解析到 40% 直接报错。处理办法是绕过它用loader.parse传 ArrayBuffer 而不是让 loader 自己去拉文件后面会详细写。2.3 模型格式选型glTF、GLB 与 OBJ 在小程序的兼容性对比外部 3D 模型格式选型直接决定你在小程序里要写多少兼容代码。我建议优先选 GLB其次是 glTF 2.0OBJ 除非是遗留资源否则不要碰。GLB 是二进制单文件模型几何、材质、动画、纹理全部打包在一个.glb文件里小程序里读取就是一次文件读操作解析路径单一。glTF 则可能是.gltf.bin 若干纹理文件的组合小程序端读取需要自己处理相对路径依赖每个外部引用都可能成为加载失败点。OBJ 是老格式材质用单独的.mtl纹理引用路径管理更繁琐而且现代 PBR 材质参数支持很差做出来的效果偏旧。格式文件构成小程序加载成本材质支持推荐度GLB单文件低一次读取PBR 完整推荐glTF 2.0主文件 bin 纹理高需处理依赖PBR 完整有条件OBJobj mtl 纹理高路径繁琐基本无 PBR不推荐还有一个需要留意的是 Draco 压缩。Draco 能把模型体积压缩到三分之一甚至更低但解压需要一个解码器浏览器端从 CDN 加载 wasm小程序里没有这个条件。适配版运行时对 Draco 的支持要看是否内置了解码器实现如果没内置模型解析时会直接报错建议在导出模型时关闭 Draco 压缩改用 gltf-pipeline 的纹理压缩和网格精简后面第 4 章展开。3. 把模型加载跑通从初始化到首个外部模型上屏这一章是核心操作链路。我按一个最简可运行的顺序来写先拿 canvas 节点创建渲染器再读取模型文件并解析然后挂进场景开渲染循环最后处理触摸旋转。每一步都会给代码和关键参数解释。3.1 获取 Canvas 节点并创建 WebGL 渲染器WXML 侧需要准备一个 canvas 组件type属性在小程序基础库 2.9.0 以后支持webgl建议直接声明为 webgl 类型。注意 canvas 的宽高不要写死让样式决定布局尺寸像素尺寸由脚本根据像素比计算。canvas idgl-canvas typewebgl classcanvas-3d stylewidth: 100%; height: 100%;/canvas对应的初始化逻辑在onReady里执行。先拿到 canvas 节点然后调用适配运行时创建作用域内的 Three.js 实例。import { createScopedThreejs } from threejs-miniprogram Page({ data: {}, onReady() { const query wx.createSelectorQuery() query.select(#gl-canvas).fields({ node: true, size: true }).exec((res) { const canvas res[0].node const windowInfo wx.getWindowInfo() const dpr windowInfo.pixelRatio || 2 canvas.width windowInfo.windowWidth * dpr canvas.height windowInfo.windowHeight * dpr const three createScopedThreejs(canvas) this.three three const renderer new three.WebGLRenderer({ canvas, antialias: true, alpha: true }) renderer.setPixelRatio(dpr) renderer.setSize(windowInfo.windowWidth, windowInfo.windowHeight, false) this.renderer renderer this.initScene() this.loadModel() this.startRenderLoop() }) }, initScene() { const three this.three this.scene new three.Scene() this.camera new three.PerspectiveCamera(45, this.data.width / this.data.height, 0.1, 1000) this.camera.position.set(0, 0, 5) } })代码里的几个关键点canvas.width windowInfo.windowWidth * dpr是把 canvas 内部像素分辨率设置为屏幕物理分辨率避免字体和边缘发虚。renderer.setSize(w, h, false)第三个参数false表示不修改 canvas 的样式尺寸样式由 WXML 里的 class 控制这个参数很多人漏掉一旦为truecanvas 的 CSS 高度会被设置成像素值在部分机型上导致布局异常。createScopedThreejs(canvas)返回的three对象是一个完整的命名空间包含Scene、PerspectiveCamera、WebGLRenderer、GLTFLoader等所有需要用的类。创建渲染器时如果看控制台提示webgl context lost一般是 canvas 类型不是 webgl或者基础库版本过低。建议在真机上调试而不是开发者工具开发者工具的 WebGL 实现与真机差异不小。3.2 读取并解析外部模型用 loader.parse 替代 load在小程序里GLTFLoader 的load(url)方法通常不可用因为它内部走 XMLHttpRequest 拉文件适配版运行时虽然实现了网络层但路径解析和跨域边界很磨人。我更习惯的做法是先把模型文件变成 ArrayBuffer再调用loader.parse(arrayBuffer, path, onLoad, onError)把加载控制权握在手里。loadModel() { const three this.three const loader new three.GLTFLoader() const fs wx.getFileSystemManager() fs.readFile({ filePath: /models/robot.glb, success: (res) { loader.parse(res.data, , (gltf) { this.model gltf.scene this.scene.add(this.model) console.log(model loaded, gltf) }, (err) { console.error(model parse failed, err) }) }, fail: (err) { console.error(read file failed, err) } }) }fs.readFile的filePath传的是小程序代码包内的绝对路径以/开头模型放在项目的models目录下即可。不给encoding参数时res.data默认返回 ArrayBuffer正好满足parse的输入要求。parse的第二个参数是模型内部引用文件的解析路径对于 GLB 单文件模型传空字符串没问题如果模型是拆分的 glTF 格式这里要传对应的目录路径否则纹理和 bin 文件找不到引用。我在某个项目里接过一批拆分格式的模型.gltf文件里引用了同目录的.bin和.jpg纹理parse的 path 参数一开始传的是/models/xxx/结果纹理依然加载不出来。排查后发现适配版运行时的路径处理是直接把字符串拼到引用前而小程序的 fs 读取要求绝对路径最后改成在加载前把模型目录里的文件先复制到 USER_DATA_PATH 下再解析问题才解决。这个坑在第 5 章还会说。3.3 渲染循环与旋转交互小程序的 touch 事件替代鼠标拖拽浏览器版 Three.js 有 OrbitControls监听鼠标事件。小程序里鼠标不存在触摸事件直接绑到 canvas 节点上。手势计算本身不复杂把两次触摸的坐标差值映射成模型旋转的欧拉角即可。setupTouch() { const canvas this.canvas let lastX 0 let lastY 0 canvas.addEventListener(touchstart, (e) { const touch (e.touches e.touches[0]) || (e.changedTouches e.changedTouches[0]) if (!touch) return lastX touch.clientX lastY touch.clientY }) canvas.addEventListener(touchmove, (e) { const touch (e.touches e.touches[0]) || (e.changedTouches e.changedTouches[0]) if (!touch || !this.model) return const deltaX touch.clientX - lastX const deltaY touch.clientY - lastY this.model.rotation.y deltaX * 0.01 this.model.rotation.x deltaY * 0.01 lastX touch.clientX lastY touch.clientY }) }这个触摸处理有两个要点。第一事件对象里touches和changedTouches在真机上的表现不一致某些 Android 机型在 touchend 里touches是空数组但changedTouches有值所以做了兜底取数。第二旋转系数0.01把像素差值映射成弧度值这个系数跟模型大小有关模型越大需要的旋转速度越小可以做成可配置参数暴露出来。比直接改model.rotation更稳的做法是维护一个全局的旋转累加变量在渲染循环里赋给模型避免触摸回调执行顺序和渲染帧冲突。触摸开始后注意别让页面也跟着滚动否则滑动手势会同时触发页面滚动和模型旋转体验非常割裂。处理方式是在 canvas 上绑定事件的同时检查是否启用了catchtouchmove或者用preventDefault思路看适配运行时是否支持。我一般直接在 WXML 里给 canvas 外层包一个catchtouchmovenoop的 view把滚动吞掉。3.4 完整的生命周期管理从 onReady 到 onUnload 的资源闭环小程序页面有明确的生命周期3D 渲染资源必须在合适的时机创建与销毁。很多「用着用着就变卡」「切后台回来黑屏」的问题都是生命周期管理没做好。Page({ onReady() { this.init3D() }, onHide() { this.stopRenderLoop() }, onShow() { if (this.renderer) { this.startRenderLoop() } }, onUnload() { this.dispose3D() } })onHide在页面切到后台时触发此时渲染循环应该暂停否则 WebGL 上下文在后台仍然尝试绘制会占用 GPU 资源且可能导致部分机型闪退。onShow回来时如果渲染器还在再重新启动渲染循环。onUnload时做完整清理包括取消动画帧、释放几何体、纹理、材质和渲染器这个在第 4 章会给具体代码。我见过不少项目只在onReady里初始化忘了onUnload里释放。页面被关掉后渲染循环还在跑canvas 节点已经销毁JS 层面的定时器或 requestAnimationFrame 一直在空转内存不释放帧率越来越低最后整个小程序卡死。生命周期的闭环不是可选项是必选项。4. 性能与资源管理让小程序 3D 不卡不黑屏小程序环境的性能天花板比浏览器低不少渲染性能优化不是加分项而是上线前的必经关卡。这一章讲模型压缩、渲染参数取舍和内存释放三个方向。4.1 模型上线前的三道工序减面、纹理压缩与格式归一拿到一个外部模型后我不会直接塞进小程序里而是先做三道工序。第一道是减面把模型三角面数量压到合适范围。角色类展示模型控制在 3 万面以内工业零件类可以稍高5 万面左右是大多数中低端 Android 机型的舒适区间。面数过高时即使静态展示不旋转首帧加载也会出现几秒钟的卡顿。第二道是纹理压缩。模型的纹理贴图尽量控制在 1024 以内大部分展示场景 512 足够。把 RGB 贴图转成 JPEG有透明通道的保留 PNG但注意压缩等级。一个 2048 的 PNG 可能占 8MB 内存压缩到 512 的 JPEG 只要几百 KB对小程序包体积和运行内存都是质变。别忘了小程序主包有 2MB 的体积限制模型包能走分包就走分包能走网络加载就走网络加载。第三道是格式归一。无论交付方给的是 FBX、OBJ 还是 glTF最终统一导出为 GLB 格式。调整好单位、轴方向和材质参数后在执行导入前用 gltf-pipeline 做一次体积压缩。gltf-pipeline -i model.gltf -o model.glb -t这条命令把 glTF 转成 GLB-t参数表示转换纹理格式把非必要的纹理资源内嵌到 GLB 里。执行完检查产物大小超过 3MB 就回到模型源文件继续减面直到体积和面数同时达标再进小程序。4.2 drawCall、分辨率与帧率之间的取舍WebGL 渲染性能瓶颈通常不在顶点数量而在 drawCall 数量。drawCall 是渲染引擎向 GPU 提交一次绘制命令的次数每切换一次材质、纹理或者 shader都会增加一次 drawCall。小程序端 GPU 驱动能力参差不齐drawCall 过高会直接导致帧率跌破 30fps。降低 drawCall 的通用手段是合并几何体和材质。把模型中相同材质的网格合并成一个几何体一次 drawCall 就能画完。Three.js 里有BufferGeometryUtils.mergeGeometries可以合并几何体合并后材质保持一致。这里有个注意点合并前要先烘焙光照或贴图因为合并后无法再对单小块做差异化光照。如果模型拥有大量独立材质建议从建模阶段就规划好材质数量不要超过 5 种。分辨率取舍上renderer.setPixelRatio(dpr)的值在低端机上建议限制为 1.5 甚至 1。屏幕物理像素比越高渲染的像素量越大GPU 压力成倍上涨。一款中端安卓机的 dpr 是 2.5意味着单帧渲染面积是 750x1334 的 6.25 倍这谁扛得住。我的做法是读取设备型号中低端机统一用 dpr1仅高端机用满血 dpr。如果你的页面只是展示模型没有旋转交互需求可以改成按需渲染模式只有模型加载完成或触摸旋转时调用一次renderer.render平时不跑渲染循环。这个优化能节省大量 CPU 和 GPU 占用页面切走时也不会因为渲染循环空转导致手机发烫。4.3 内存释放页面卸载前必须做的清理动作Three.js 里创建的几何体、材质和纹理默认不会自动释放必须手动调用dispose。小程序页面的生命周期比浏览器标签页更敏感页面被销毁后如果 WebGL 资源不释放会一直占用显存。下面是一段完整的清理顺序。dispose3D() { if (this.renderLoopId) { this.canvas.cancelAnimationFrame(this.renderLoopId) } if (this.scene) { this.scene.traverse((child) { if (child.geometry) { child.geometry.dispose() } if (child.material) { if (child.material.map) { child.material.map.dispose() } child.material.dispose() } }) } if (this.renderer) { this.renderer.dispose() } }清理顺序是先取消渲染循环再遍历场景释放每个网格的几何体和材质最后释放渲染器。traverse会深度遍历场景图里的所有节点确保不会漏掉嵌套的子网格。纹理map单独释放一次是因为材质 dispose 不会自动释放其引用的纹理对象这是 Three.js 的一个设计细节很多人会在这一步漏掉纹理导致真机上的内存占用只增不减。模型反复加载卸载的场景下建议在onHide里只暂停渲染循环不要释放场景资源在onUnload里才做真正释放避免页面短暂切后台回来又要重新加载模型的尴尬。5. 避坑手册五条常见故障的现象、原因与解决这一章我整理了在小程序端调试 3D 渲染遇到最多的五类问题全部是真机或开发工具里实际出现过的表现按「现象、原因、解决」三条线来说。5.1 现象模型加载白屏且控制台没有任何报错开发工具里打开页面渲染区域一片空白console 也干净得像没跑过代码。原因是创建渲染器之前canvas 节点还没有完成布局query.select(#gl-canvas).fields({ node: true, size: true })拿到的 width 和 height 都是 0renderer.setSize(0, 0, false)导致渲染目标尺寸为零。我在第一次接手这类问题时查阅官方示例发现脚本是在onReady后才创建渲染器而我把初始化逻辑写在了onLoad里前者才是安全的时机。解决方法是把整个初始化逻辑移到onReady回调并且兜底读取一次wx.getWindowInfo()的宽高作为 canvas 像素尺寸避免依赖选择器返回的 size 字段。如果排查后确认时间点没问题再检查 WXML 里 canvas 的type是否确实声明为webgltype2d的节点在某些基础库版本下 getContext 会返回 null且报错信息被吞。5.2 现象iOS 正常但部分 Android 机型黑屏同一套代码iPhone 上模型完美显示换到某个品牌中端 Android 机直接黑屏。原因是 Android 厂商的 WebGL 驱动实现水平参差部分 GPU 不支持高精度浮点数highp float或者不支持某些纹理压缩格式。这类问题排查时用wx.getSystemInfoSync()拿到机型列表做灰度测试定位到具体机型后针对性处理。解决方法是创建渲染器时设置精度相关参数把材质 uniformity 中的精度要求降级同时关闭抗锯齿antialias: false和阴影相关特性。适配的兜底方案是在初始化渲染器时增加 try-catch捕获失败后回退到纯颜色背景避免整个页面崩掉。很多生产级项目上线时都会在后台维护一张兼容性黑名单中低端机禁用抗锯齿才能保证基础体验。5.3 现象模型解析成功但纹理全部发黑模型轮廓有了形状对但表面一片黑或者泛白纹理贴图没生效。这通常和颜色空间与纹理翻转有关。浏览器里 Three.js 默认对纹理做flipY处理而小程序的图片解码方式与浏览器不同适配运行时里flipY的行为可能被改变。解决方法是模型加载回调里手动遍历所有贴图强制设置纹理参数。另一种常见原因是 GLB 内部引用了外部纹理但parse的路径参数传错纹理解码失败后 Three.js 静默降级为黑色材质看起来就像纹理发黑。解决办法是把模型真正做成单文件 GLB纹理全部内嵌不依赖外部路径。gltf.scene.traverse((child) { if (child.isMesh child.material) { const materials Array.isArray(child.material) ? child.material : [child.material] materials.forEach((mat) { if (mat.map) { mat.map.flipY false mat.map.needsUpdate true } }) } })这段代码在模型加载完成后立即执行遍历所有网格材质把贴图的flipY设为false并标记更新。如果你发现设了flipY false后纹理上下颠倒就改成true再试因为机型差异会导致表现不统一。5.4 现象触摸旋转失效页面反而跟着滚动canvas 区域上滑动模型不动页面背景倒是滚得很欢快。这是事件冒泡问题。小程序里默认触摸事件会冒泡到 pagepage 的滚动机制优先响应。解决方法是两层处理在 WXML 的 canvas 外层包一个 view给 view 加catchtouchmovenoop写一个空方法把事件吞掉同时 canvas 自身的触摸监听改成touchstart、touchmove里主动调用event.preventDefault。需要说明的是适配版本对 canvas node 的事件对象实现有差异某些版本里touchmove回调传的不是标准 TouchEvent需要读到clientX在e.touches里不存在时就去e.changedTouches里找这个和 3.3 节的处理是同一套逻辑。如果你对 canvas 绑定事件不放心可以把触摸事件绑定到 page 的onTouchStart和onTouchMove上在 Page 配置里声明再通过坐标判断触摸点是否落在 canvas 区域内命中再处理旋转这个方案兼容性更好但代码稍微绕一点。5.5 现象引入 npm 包后编译直接报错下载资源后按文档引入 Three.js 适配包开发者工具直接报Module not found: Cant resolve path或类似错误。原因是适配包依赖了 Node.js 核心模块而小程序运行时没有这些模块。不少人在这一步就卡住放弃了。解决方法是先确认小程序开发者工具已经开启 「ES6 转 ES5」和「增强编译」然后执行工具的「构建 npm」把依赖打进miniprogram_npm目录。如果构建后仍然报 Node 核心模块缺失就把构建产物里的process、Buffer等引用做全局替换或者在页面顶部手动注入 polyfill。这块确实很磨人是适配包在小程序里落地的第一道门槛。我的建议是直接把适配包源码放到项目的libs目录下自己手动维护构建虽然原始但可控。当前端构建链路出问题时最简单直接的解法往往不是修依赖而是绕过依赖。6. 进阶封装一个可复用的模型展示组件当 3D 展示需求从一个页面扩散到多个页面时把加载逻辑封装成自定义组件是必然选择。组件化之后页面里只需要写一行标签传入模型地址就能展示。先定义组件的属性接口和生命周期。modelUrl和autoRotate是核心属性前者告诉组件要加载哪个模型后者控制是否自动旋转。组件的ready生命周期里做 canvas 初始化和模型加载detached里做资源释放。Component({ properties: { modelUrl: { type: String, value: }, autoRotate: { type: Boolean, value: true } }, data: { loading: true, errorMessage: }, lifetimes: { ready() { this.init() }, detached() { this.dispose() } }, methods: { init() { const query this.createSelectorQuery() query.select(#viewer-canvas).fields({ node: true, size: true }).exec((res) { // 创建渲染器、加载模型 }) }, dispose() { // 释放资源 } } })组件化的一个关键是 canvas 的id不能写死。页面里如果使用了多个组件实例每个实例的 canvas id 必须唯一否则选择器会查到第一个实例的节点。推荐做法是在lifetimes.attached里生成一个随机 id 存入 dataWXML 里动态绑定。另一个设计是错误上报。组件内部遇到模型加载失败时除了显示错误文案还要通过triggerEvent(error, detail)把错误信息抛给页面方便页面埋点或做提示。加载成功时触发triggerEvent(load, detail)页面可以在这时隐藏全局 loading。组件内部的自动旋转逻辑可以做成根据时间增量累加角度而不是每帧固定加一个值保证不同帧率下旋转速度一致。角度累加放在 requestAnimationFrame 回调里用上一帧到当前帧的时间差乘以一个恒定角速度这样 60fps 和 30fps 的设备看起来转速相同。封装完组件后页面侧的使用就非常简洁了。后续接手项目的同事不用理解 WebGL 细节只要传modelUrl和autoRotate就行。说到底小程序 3D 渲染的难点从来不在代码量而在环境适配的细节里。从那以后我每次接到小程序 3D 需求都会强制自己先花半小时过一遍「canvas 节点获取、模型格式确认、生命周期闭环、中低端机兼容、资源释放」这五件事能提前排除大部分雷希望这份笔记里的经验也能帮你少走几趟弯路。本文还有配套的精品资源点击获取