小程序 Three.js 3D 渲染实战：GLTF 模型加载与性能优化

简介面向微信小程序开发者的 three.js 3D 模型展示示例适合希望在轻量级项目中快速接入三维视图、梳理渲染流程与动画调节思路的初中级开发者。压缩包共 18 个文件约 258KB包含 8 个 js 逻辑脚本、5 个 json 配置、2 个 wxss 样式、2 个 wxml 页面结构及 1 个 gltf 虾模型页面、组件、工具脚本与配置分层组织便于定位三维场景初始化、模型路径与页面样式等关键环节。示例围绕小程序环境加载并展示 3D 模型展开源码中预留了可调整的函数入口读者可据此尝试旋转、掉落等动画效果并参考模型上传服务器后在 wxml 中通过 url 引用的做法。已有 2309 人学习适合用作快速上手与避坑参照也能帮助理解 three.js 在小程序中的基础组织方式与调试要点。对准备做课程设计、作品展示或功能验证的读者较友好也可作为二次开发的基础模板。1. 小程序里跑 Three.js先弄明白它凭什么渲染出第一帧在微信小程序里做 3D 展示需求通常很具体商品转一圈看材质、设备模型放大看结构、展厅模型拖拽缩放。选择 Three.js 是因为生态最全GLTF、PBR 材质、光照、后处理都有现成方案但直接把 npm 上的three装进小程序第一行就会报document is not defined因为它默认依赖浏览器 DOM 那套东西。这项工作要解决的核心问题是用 canvas node 加一层适配让 3D 渲染管线在小程序容器里真正跑起来。适合已经会写小程序页面、手上有一个 glb 模型、需要尽快交出可交互展示页的同学也适合已经跑通但卡在黑屏、卡顿、二次进入白屏的人。2. 工程骨架threejs-miniprogram 适配层怎么补上缺失的 DOM2.1 适配层补的几个关键接口canvas、rAF、ImageThree.js 在浏览器里依赖四类环境能力document.createElementNS用来造 canvas、window.requestAnimationFrame驱动渲染循环、new Image()加载贴图、XMLHttpRequest加载外部资源。小程序运行环境里这四样一个都没有只有wx.createSelectorQuery().node()拿到的 canvas 节点以及它自带的getContext(webgl)。threejs-miniprogram这个适配包的思路不是改 Three.js 源码而是用传入的 canvas 节点反造一个极简的伪 document 和伪 window把 WebGL 上下文挂上去再在内部new THREE.WebGLRenderer时取到这个上下文。它暴露的核心 API 只有一个// 适配层入口传入 canvas 节点返回一套独立的 THREE 命名空间 const { createScopedThreejs } require(threejs-miniprogram) // 注意 createScopedThreejs 不是单例每次调用都是一套新的 THREE // 多页面、多实例场景下互不污染但也意味着不能跨页面共享 geometry const THREE createScopedThreejs(canvas)理解scoped这个词很重要。它返回的是隔离过的 Three 对象不是全局那个THREE。因此你从别处搬来的GLTFLoader、OrbitControls如果内部写死了全局THREE直接 import 会拿不到类。常见做法是在createScopedThreejs之后把global.THREE临时指过去再 require 那些老式 examples 脚本用完再置空。这个做法看起来不优雅但在小程序这种没有模块劫持能力的环境里它是最省事的做法。2.2 从空目录到能编译依赖安装与页面配置先把 npm 依赖装上。小程序官方脚手架支持 npm 构建前提是在开发者工具里勾选“使用 npm 模块”然后执行一次“构建 npm”把node_modules里的包转成小程序可识别的miniprogram_npm。这一步漏掉运行时会直接报模块找不到。# 在项目根目录执行threejs-miniprogram 是适配包不是 three 本体 npm i threejs-miniprogram --save # 装完后必须手动触发一次“构建 npm”产物在 miniprogram_npm 目录页面配置上canvas 必须显式声明typewebgl否则拿到的是 2D 上下文WebGL 调用全部静默失败。这一点没有报错是最容易卡住的地方之一。!-- pages/viewer/viewer.wxml -- canvas idgl typewebgl classgl disable-scroll{{true}} bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd /canvas/* 宽高必须给死canvas 没有内容撑高的概念高度为 0 就是黑屏 */ .gl { display: block; width: 100%; height: 600rpx; }disable-scroll这个属性建议加上。手指在 canvas 上左右拖动旋转模型时页面的纵向滚动会同时触发手感会很怪加上之后触摸事件会被 canvas 吃掉旋转才跟手。基础库需要 2.7.0 以上才支持typewebgl的 node 查询低版本只能用canvas-id那套旧接口适配层不兼容所以上线前把最低基础库版本提上去是必要动作。2.3 最小可运行一个能被手指带着转的立方体先不加载模型用一个立方体把链路打通。这一步的意义是把“黑屏到底是环境问题还是模型问题”区分开后面加载模型出问题时你手上有一个已知能跑的对照。// pages/viewer/viewer.js const { createScopedThreejs } require(threejs-miniprogram) Page({ onReady() { // 必须放在 onReadyonLoad 阶段节点还没渲染出来查询结果是 null this.initScene() }, initScene() { wx.createSelectorQuery() .select(#gl) .node() .exec((res) { const canvas res[0].node if (!canvas) { console.error(canvas 节点为空检查 typewebgl 和基础库版本) return } this._canvas canvas const THREE createScopedThreejs(canvas) // 像素缓冲按 dpr 放大但上限压到 2低端机开 3 会明显掉帧 const win wx.getWindowInfo ? wx.getWindowInfo() : wx.getSystemInfoSync() const dpr Math.min(win.pixelRatio || 2, 2) const width win.windowWidth const height width * 0.8 // 与 wxss 中 600rpx 的宽高比保持一致 const renderer new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true }) renderer.setPixelRatio(dpr) // 第三个参数 false 表示不要让 Three 去改 canvas 的 style // 小程序里 style 归 wxss 管传 true 会把尺寸覆盖成 px布局会错位 renderer.setSize(width, height, false) const scene new THREE.Scene() const camera new THREE.PerspectiveCamera(45, width / height, 0.1, 100) camera.position.set(0, 0, 3.2) const dirLight new THREE.DirectionalLight(0xffffff, 1.2) dirLight.position.set(2, 3, 4) scene.add(dirLight) scene.add(new THREE.AmbientLight(0xffffff, 0.6)) const cube new THREE.Mesh( new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0x4a90d9, roughness: 0.4 }) ) scene.add(cube) this._model cube this._scene scene this._renderer renderer const clock new THREE.Clock() const loop () { cube.rotation.y clock.getDelta() * 0.8 renderer.render(scene, camera) // 用 canvas 节点的 rAF不是全局 window.requestAnimationFrame this._raf canvas.requestAnimationFrame(loop) } this._raf canvas.requestAnimationFrame(loop) }) }, onUnload() { if (this._raf this._canvas) this._canvas.cancelAnimationFrame(this._raf) } })几个参数值得单独说。setPixelRatio传的是设备像素比它决定实际渲染的像素缓冲大小直接影响清晰度和 GPU 负载2 是清晰度和性能的平衡点setSize的第三个参数在小程序里几乎必须传false因为 canvas 的视觉尺寸由 wxss 决定让渲染器再写一次 style 会造成尺寸二义性表现就是模型被拉伸或者只渲染左下角一块渲染循环里用的canvas.requestAnimationFrame和取消用的canvas.cancelAnimationFrame必须来自同一个 canvas 节点跨节点调用不会生效页面卸载后循环还在跑这是内存泄漏的常见源头。3. 模型加载链路GLTF 从服务端到小程序 canvas 的完整路径3.1 格式选型为什么 GLTF 比 OBJ、FBX 更适合这个场景小程序对包体和内存都比较敏感模型格式的选择直接决定首屏体验。常见的几种格式在这个场景下的差别很明显格式单文件内嵌贴图动画解析依赖适合场景GLB是支持支持GLTFLoader首选一次请求拿全GLTF bin 贴图否分离支持GLTFLoader需要按需替换贴图时OBJ否不支持不支持OBJLoader MTLLoader只有几何体的老资源FBX是支持支持FBXLoader体积大美术源文件不建议直出STL是不支持不支持STLLoader无材质工业件单色预览我一般要求美术导出 GLB理由有三个单文件少一次网络往返小程序并发请求本身就有开销GLTF 的 PBR 材质和 Three.js 的MeshStandardMaterial是一一对应的不用做材质转换动画是采样式的关键帧解析成本比 FBX 低一个量级。体积上压缩后的 GLB 控制在 3MB 以内比较稳妥超过这个数在 4G 网络下首帧等待会明显超出用户耐心阈值需要走后面第 6 章的预下载。3.2 用 wx.downloadFile 接管文件加载Three.js 的FileLoader内部用的是XMLHttpRequest小程序没有这个对象所以要么改写FileLoader要么干脆绕过它自己下载完直接调loader.parse。后者更可控我一般用这种方式因为下载失败、状态码异常、文件读取出错这三类问题都能分别拿到错误信息而不是一个笼统的 onError。// utils/load-model.js function loadGLB(THREE, loader, url, onLoad, onError) { wx.downloadFile({ url, success(res) { if (res.statusCode ! 200) { onError(new Error(模型下载失败HTTP res.statusCode)) return } // 临时文件路径只能通过文件系统接口读不能直接 fetch wx.getFileSystemManager().readFile({ filePath: res.tempFilePath, success(file) { // 第二个参数是资源基路径贴图的相对路径会基于它拼接 // 传错会导致贴图全部 404但模型本体正常显示 const basePath url.slice(0, url.lastIndexOf(/) 1) loader.parse(file.data, basePath, onLoad, onError) }, fail: onError }) }, fail: onError }) } module.exports { loadGLB }wx.downloadFile需要在后台配置 downloadFile 合法域名这一条在开发工具里勾了“不校验合法域名”能跑通真机预览立刻失败是新人最常踩的坑之一。readFile不传 encoding 时返回的是 ArrayBuffer正好是parse需要的类型。parse的第二个参数容易被忽略它决定了 gltf 里uri: textures/base.png这类相对路径拼出来的完整地址如果模型用的是外置贴图而这里传了空字符串贴图会全部加载失败但几何体和材质颜色仍然正常表现为“模型是灰的”。3.3 贴图加载ImageLoader 必须替换GLTFLoader 内部加载贴图走的是THREE.ImageLoader而它的实现是document.createElement(img)。小程序没有 document所以即便模型解析成功贴图也一定加载不出来。替换方案是用 canvas 节点自带的createImage()它返回的对象接口和浏览器 Image 基本一致支持 onload、onerror 和 src 赋值。// utils/patch-image-loader.js module.exports function patchImageLoader(THREE, canvas) { THREE.ImageLoader.prototype.load function (url, onLoad, onProgress, onError) { // GLB 内嵌纹理会生成 blob: 开头的临时地址 // 小程序的 createImage 不支持 blob 协议这里直接跳过并给出提示 if (/^blob:/.test(url)) { console.warn(跳过 blob 贴图建议导出时把贴图外置或转成 base64) return } const img canvas.createImage() img.onload () onLoad(img) img.onerror (e) onError onError(e) img.src url return img } }这段代码里最值得注意的是 blob 那个分支。GLB 把贴图内嵌在二进制里时GLTFLoader 会通过URL.createObjectURL生成一个临时地址而小程序既没有URL对象也没有 blob 协议支持这条路是断的。解决办法有两个一是导出时用“GLTF 分离”模式贴图作为独立的 png 放在同目录靠 basePath 拼地址加载二是让美术把贴图压到很小后用 base64 data URI 内嵌createImage对 data URI 是支持的。我在项目里一般选第一种因为分离式贴图可以单独做 CDN 缓存和格式转换改图不用重新导出整个模型。4. 交互与性能触摸控制、帧率、内存三道关4.1 自己写触摸旋转与双指缩放比搬 OrbitControls 更稳OrbitControls依赖window上的事件监听和document元素在小程序里搬过来要改的地方比写一套还多。展示类场景的交互其实只有三件事单指拖动旋转、双指捏合缩放、惯性回弹可选自己写不到一百行参数还完全可控。// 在 Page 对象上补充三个触摸处理函数 onTouchStart(e) { if (e.touches.length 1) { this._touch { mode: rotate, x: e.touches[0].x, y: e.touches[0].y } } else if (e.touches.length 2) { const [a, b] e.touches this._touch { mode: zoom, dist: Math.hypot(a.x - b.x, a.y - b.y) } } }, onTouchMove(e) { const t this._touch if (!t || !this._model) return if (t.mode rotate e.touches.length 1) { const dx e.touches[0].x - t.x const dy e.touches[0].y - t.y // 0.008 是屏幕像素到弧度的换算系数调大转得快调小更跟手 this._model.rotation.y dx * 0.008 this._model.rotation.x dy * 0.008 // 俯仰角限幅避免模型被翻到背面看到中空结构 const limit Math.PI / 3 this._model.rotation.x Math.max(-limit, Math.min(limit, this._model.rotation.x)) t.x e.touches[0].x t.y e.touches[0].y } if (t.mode zoom e.touches.length 2) { const [a, b] e.touches const dist Math.hypot(a.x - b.x, a.y - b.y) // 用乘法而不是加法缩放手感才均匀 this._model.scale.multiplyScalar(dist / t.dist) const s this._model.scale.x // 缩放上下限防止缩成一个点或者撑满到看不见边缘 if (s 0.4 || s 4) this._model.scale.setScalar(Math.max(0.4, Math.min(4, s))) t.dist dist } }, onTouchEnd() { this._touch null }坐标取的是touches[0].x / y这是 canvas 组件坐标系里相对左上角的位置比clientX更准因为页面可能有滚动偏移。旋转系数 0.008 不是随便写的它大致等于“拖动 100 像素转 45 度”和主流电商 3D 展示的手感比较接近如果模型本身尺寸很大可以适当调小到 0.005。缩放用multiplyScalar而不是直接赋值是为了保留模型原始缩放比例很多 GLB 导出时自带 0.01 这种单位换算直接赋值会把比例冲掉。4.2 帧率与像素比setPixelRatio 的取值边界帧率的瓶颈通常不在 JS 逻辑而在 GPU 的填充率。小程序 canvas 的实际渲染分辨率等于 CSS 尺寸乘以 pixelRatio一台 dpr 为 3 的手机开满像素比渲染面积是 dpr 为 1 的九倍中低端芯片很容易掉到 20 帧以下。我一般按下面的规则取设备像素比建议 setPixelRatio说明11无需处理22大多数机型清晰度和性能平衡3 及以上2上限压到 2肉眼差异很小低端机内存小于 3GB1.5靠 canvas 的 CSS 尺寸撑清晰度判断低端机没有官方接口常见做法是用wx.getDeviceInfo()里的benchmarkLevel它是 iOS 和部分安卓机型提供的性能等级小于 10 的按低端处理。这只是估算真机上还是要靠实测帧率来定思路是在渲染循环里每秒统计一次帧数把结果打到 console 里连续跑 30 秒看波动let frames 0 let lastTick Date.now() const loop () { frames const now Date.now() if (now - lastTick 1000) { console.log(fps, frames, pixelRatio, renderer.getPixelRatio()) frames 0 lastTick now } renderer.render(scene, camera) this._raf canvas.requestAnimationFrame(loop) }如果 fps 稳定在 55 以上说明还有余量掉到 40 以下就要动手了优先降 pixelRatio其次降 antialias最后才是减面。抗锯齿这个选项在小屏幕上收益不明显开销却不小低端机可以直接关掉。4.3 页面返回后的资源释放与 context 数量限制小程序对同时存在的 WebGL context 数量有上限iOS 上尤其明显。如果每次进入 3D 页面都新建 renderer 而不释放来回进出几次之后就会拿不到新的 context表现是页面白屏但没有任何报错这个现象最让人困惑。释放要分三层做几何体、材质、纹理每一层都有dispose()renderer 自身要dispose()有条件的话再调forceContextLoss()主动交还上下文。纹理藏在材质的各个属性里所以遍历材质对象的键是最省事的写法。onUnload() { const { _renderer: renderer, _scene: scene, _canvas: canvas, _raf: raf } this if (raf canvas) canvas.cancelAnimationFrame(raf) if (scene) { scene.traverse((obj) { if (obj.geometry) obj.geometry.dispose() const mats Array.isArray(obj.material) ? obj.material : [obj.material] mats.forEach((m) { if (!m) return // 材质上的贴图属性名不固定遍历一遍最保险 Object.keys(m).forEach((key) { const val m[key] if (val val.isTexture) val.dispose() }) m.dispose() }) }) scene.clear() } if (renderer) { renderer.dispose() if (renderer.forceContextLoss) renderer.forceContextLoss() } this._model null this._scene null this._renderer null }scene.clear()是清空子节点引用traverse里做的才是真正释放 GPU 资源两者顺序不能反。forceContextLoss不是所有版本都有调用前要判断存在性。这套释放逻辑建议封装成一个disposeScene(renderer, scene)工具函数每个 3D 页面卸载时都调用一次别指望某一次忘了之后靠重进页面自愈那种情况只会越积越多。5. 避坑与排查五个真实翻车现场的现象、原因和解决5.1 渲染类黑屏、半屏、拉伸现象一页面一片空白控制台没有任何报错。原因通常是createSelectorQuery放在了onLoad里执行此时 canvas 节点还没完成渲染拿到的res[0].node是 undefined后续代码被静默跳过。也可能是type写成了默认值拿到的是 2D 上下文new THREE.WebGLRenderer时不报错但什么也画不出来。解决方式是把初始化挪进onReady并且在拿到节点后加一行判空日志把“节点没拿到”和“渲染出错”区分开。现象二模型只在 canvas 左下角占四分之一或者被横向拉宽。这是像素缓冲和 CSS 尺寸不一致导致的。常见写法是renderer.setSize(w, h)不传第三个参数Three 默认会去改 canvas 的 style 宽高而小程序里 canvas 的视觉尺寸由 wxss 决定两套尺寸打架就会错位。统一改成setSize(w, h, false)并且让 w、h 与 wxss 里的宽高比严格对应问题就消失了。像素比也要同步设置只设setSize不设setPixelRatio在高分屏上会糊成一团。现象三iOS 上模型全黑安卓正常。优先查光照和色彩空间。GLTF 的贴图默认按 sRGB 处理如果手动设置过texture.colorSpace或者用了老版本的encodingiOS 的渲染路径可能和安卓不一致。另一个常见原因是环境光强度给得太低MeshStandardMaterial在没有环境贴图的情况下非常依赖方向光把AmbientLight强度提到 0.6 以上再试能快速确认是不是光照问题。5.2 加载类模型 404 与贴图丢失现象开发工具里模型正常真机预览加载失败。八成是 downloadFile 合法域名没配。开发工具可以勾选“不校验合法域名”绕过真机没有这个开关。解决方式是在后台把模型所在的 CDN 域名加进 downloadFile 白名单注意是 downloadFile 不是 request两个白名单是分开配置的。另外 URL 里带中文或者空格时要做encodeURI否则部分安卓机在拼接请求时会截断。现象模型出来了但整体是灰白色没有纹理。前面提过loader.parse的第二个参数传空会导致相对路径拼不出来。还有一种情况是贴图确实请求到了但flipY不对表现为纹理上下颠倒这种情况在 GLTF 里一般不会出现因为 GLTFLoader 内部会处理但如果你手动替换过TextureLoader就可能踩到。现象贴图全部加载失败控制台出现 blob 相关警告。GLB 内嵌贴图会走URL.createObjectURL小程序环境没有这个 API。解决办法在第 3 章讲过改成 GLTF 分离导出或者把贴图压成 base64。这个坑的隐蔽之处在于模型本体完全正常只是没有颜色容易误判成材质参数问题。5.3 性能类卡顿、闪退、二次进入失败现象第一次进页面正常返回再进就白屏。WebGL context 没有释放累计到上限后新的 renderer 创建失败但不抛错。排查方式是每次创建 renderer 后打一条日志带序号看第几次开始拿不到。修复就是在onUnload里执行完整的 dispose 链路包括forceContextLoss。现象页面越用越卡setData 之后尤其明显。把 Three 的对象塞进了data里。Three 的 scene、mesh 内部有大量循环引用setData会尝试深度序列化直接卡死主线程。正确做法是 Three 相关对象全部挂在this上data里只放loading、error这类基础状态。这条经验是用一次线上事故换来的当时一个页面进去就卡三秒查了半天才发现是某个同学把renderer放进了 data。现象模型面数不高但帧率很低。多半是渲染分辨率太高或者材质用了大量透明贴图。透明材质会关闭深度写入产生过度绘制几层叠在一起开销翻倍。可以在真机上临时把 pixelRatio 降到 1 对比帧率如果提升明显就说明是填充率瓶颈按 4.2 的表格调整即可。6. 进阶把模型首帧压进 1.5 秒的做法与验证方式6.1 预下载与本地缓存3D 页面的首帧时间主要由模型下载决定所以最有效的手段是把下载提前。我的做法是在首页onLoad时就把模型downloadFile下来把临时路径挂到getApp().globalData上用户点进 3D 页时直接读本地文件省掉一次网络往返。临时文件在本次小程序生命周期内有效退出后失效所以还需要配合wx.setStorage记录版本号版本不变时用wx.saveFile存成持久文件避免每次冷启动都重新下载。// app.js 里做一次预热注意别阻塞首页渲染 wx.downloadFile({ url: MODEL_URL, success(res) { if (res.statusCode 200) getApp().globalData.modelPath res.tempFilePath } })6.2 用打点验证首帧时间而不是凭感觉优化有没有效果得用同一套打点去量。我在三个位置埋时间戳页面onReady、模型parse成功、第一帧render完成三者相减分别得到初始化耗时和渲染耗时。真机上连续跑五次取中位数比开发工具里的数字可靠得多。如果初始化耗时超过 300ms多半是 renderer 创建或场景构建有冗余如果渲染耗时超过 800ms则要回到下载和解析环节去找原因。这套打点我一般会保留在代码里用__DEV__之类的开关控制是否输出方便上线后回捞问题。写到这里也提醒一句适配层、加载链路、释放逻辑这三块我每次新开项目都会从头走一遍最小立方体确认链路通了再上模型。有次跳过了这一步直接拿生产模型调了两天最后发现是 canvas 的type属性写漏了这种低级错误在复杂现场里最难看见。希望这些经验能帮你少走点弯路。本文还有配套的精品资源点击获取