简介面向微信小程序开发者的Three.js三维模型展示示例重点解决在小程序环境中引入Three.js并渲染GLTF格式模型的兼容性与加载路径问题。资源包共18个文件包含8个JavaScript脚本、5个JSON配置文件、2个WXML页面结构、2个WXSS样式文件以及1个GLTF虾模型压缩包整体仅258KB体积轻巧便于部署。将GLTF模型上传至服务器后在WXML中通过URL引用即可显示项目内设有页面目录与组件目录Three.js作为独立组件封装结构清晰可直接复用模型加载逻辑集中在一个模块内方便替换成自己的模型。通过调整脚本中的函数可快速实现模型旋转、掉落等多种动画效果同时附带博主实际测试后的避坑经验缩短环境调试与踩坑时间。目前已有2305人学习下载适合需要快速集成三维展示能力或入门微信小程序三维开发的技术人员。1. 微信小程序里跑threejs为什么工程化比渲染本身更难“微信小程序使用threejs实现3D模型的展示”这句话听起来只是把网页端那套搬过来但我第一次做的时候连threejs的npm包都没能顺利跑起来。小程序里没有window、没有documentcanvas的获取方式和Web端完全不一样threejs官方包直接import进来第一步就会报错。这篇文章要从环境适配讲到GLTF模型加载再到真机上的性能与资源维护把我实际踩过的坑一并讲清楚。适合正在做商品展示、3D预览这类需求且希望在可控成本内让模型在小程序里稳定跑起来的人。2. 环境搭建与适配把threejs接进小程序前的三个选择在小程序里使用threejs本质上不是“用哪个版本的库”的问题而是先解决三个前置选择渲染环境怎么接、模型数据用什么格式、threejs代码怎么打包进小程序。这三个问题不先定下来后面每一步都会返工。2.1 小程序渲染环境与threejs版本的适配思路小程序侧的3D渲染依赖Canvas组件的webgl模式。开发者工具和真机上的Canvas API与浏览器差异不小其中最核心的差异是浏览器里document.createElement(canvas)随手可用小程序里必须先在wxml声明canvas typewebgl再通过wx.createSelectorQuery()拿到底层节点的引用。threejs默认的WebGLRenderer内部会创建自己的canvas适配时必须把canvas参数显式传进去告诉它用哪个画布。我一般会把适配层单独拆成一个模块而不是在业务代码里到处改threejs的全局引用。这里先给出我在项目里固定使用的目录结构miniprogram/ ├── pages/ │ └── model-view/ │ ├── model-view.wxml │ ├── model-view.js │ └── model-view.json ├── utils/ │ ├── three-adapter.js // 小程序环境适配 │ └── model-loader.js // 模型加载封装 └── miniprogram_npm/ └── three // 构建npm后的threejs产物适配层的作用很单纯处理window、document、Image这些浏览器全局对象的缺失并把requestAnimationFrame映射到小程序的canvas节流机制上。第一次做的时候我直接npm i three然后原样import开发者工具瞬间红了错误信息全是window is not defined。后来我才把适配逻辑固定成独立文件避免每次升级threejs都重新踩一遍。2.2 模型格式选型为什么GLB是首选模型文件格式直接决定了加载链路和贴图处理的复杂度。我在实际项目中对比过GLTF、GLB、OBJ和FBX四种选型结果如下格式是否推荐主要原因GLB强烈推荐单文件包含几何、材质、贴图二进制体积小小程序侧加载路径最简单GLTF不推荐直接使用分离的.bin和贴图文件需要额外处理URL路径小程序的网络栈和本地包管理会让路径问题放大OBJ偶用结构简单但材质和贴图依赖MTL且没有动画支持适合低精度静态模型FBX不推荐需要额外解析器体积大小程序场景下收益低GLB本质上是GLTF的二进制容器把模型和贴图打包成一个文件。对小程序这种网络加载链路受限制的环境单个文件的优势很明显不需要二次下载纹理也不需要考虑相对路径在真机上会不会失效。后端给GLB文件前端只管加载出错面最小。如果你拿到的模型是FBX或OBJ我一般会让美术同事在导出时直接转成GLB而不是在代码里做格式转换。2.3 构建npm与入口配置threejs不能直接用原生小程序包管理方式引用需要用开发者工具的“构建npm”功能把npm依赖编译到miniprogram_npm目录下。构建之前需要在package.json声明依赖并在开发者工具里勾选“使用npm模块”。我用的是下面这套基础配置{ name: miniprogram-3d-demo, version: 1.0.0, dependencies: { three: ^0.160.0 } }配置说明three依赖建议锁定在某个中近期稳定版本不要直接追最新版。threejs迭代很快新版API变动会直接影响适配层的可用性。构建完成后页面的json文件里要声明使用组件或直接跳过组件模式在Page里加载适配后的threejs模块。这里有一个常见误区构建npm之后直接import * as THREE from three仍然会报错因为产物里的全局环境判断依然走浏览器分支。需要在导入前先执行适配层或者在构建产物里做一次轻量替换。对于大多数场景不需要每次从零适配。我的做法是第一次构建好之后把miniprogram_npm目录连同适配层一起放进项目的公共依赖中后续新页面直接复用不再重复走构建流程。npm的版本号也不要频繁变动否则会出现Canvas上下文创建成功但渲染器内部报错这类定位成本极高的问题。3. 加载与渲染用GLTFLoader把模型放进场景环境打通之后才进入真正有意思的部分把模型加载进来并渲染出来。这里有两个容易翻车的地方Canvas生命周期与渲染器创建时机没有对齐以及GLTF模型加载回调里的细节处理不当。3.1 Canvas节点获取与renderer生命周期对齐小程序里获取canvas节点的标准做法是通过wx.createSelectorQuery()而且必须等页面onReady之后执行。如果放在onLoad里节点还没挂载查询结果只会是undefined。我在代码里会这样处理Page({ onReady() { wx.createSelectorQuery() .select(#modelCanvas) .fields({ node: true, size: true }) .exec((res) { const canvas res[0].node; const width res[0].width; const height res[0].height; this.initRenderer(canvas, width, height); }); }, initRenderer(canvas, width, height) { // 这里传入适配后的THREE确保使用小程序环境的Canvas const renderer new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true, }); renderer.setSize(width, height); renderer.setPixelRatio(1); // 这里先固定为1后面优化时会讲到 this.renderer renderer; }, });关键点是selectorQuery的fields({ node: true, size: true })必须同时取node和size因为canvas的物理像素宽度不一定等于样式像素宽度。真机上容易出现拿到node却没有width的情况这时renderer.setSize会因为undefined产生一串NaN。先取尺寸再建renderer是为了让渲染器从一开始就知道画布真实尺寸避免后续resize逻辑混乱。另外THREE.WebGLRenderer的canvas参数在适配版本里是必传的。如果不传threejs内部会尝试创建自己的canvas而小程序环境没有document.createElement这一行就直接抛异常。这个坑的隐藏性很强因为开发者工具的控制台可能只提示Cannot read property createElement of undefined不熟悉threejs内部实现的人会误以为是版本问题。3.2 GLTFLoader加载与渲染循环加载GLB模型三步就够实例化loader、调用load、把模型加入到场景然后跑渲染循环。但实际落地时模型尺寸、位置、相机距离这三个值经常导致画面里什么都看不到。我通常会先把场景、相机和灯光准备好再加载模型import { Scene, PerspectiveCamera, AmbientLight, DirectionalLight } from three; import { GLTFLoader } from three/examples/jsm/loaders/GLTFLoader.js; const scene new Scene(); const camera new PerspectiveCamera(45, width / height, 0.1, 1000); camera.position.set(5, 5, 10); camera.lookAt(0, 0, 0); const ambientLight new AmbientLight(0xffffff, 0.6); scene.add(ambientLight); const dirLight new DirectionalLight(0xffffff, 0.8); dirLight.position.set(10, 20, 10); scene.add(dirLight); const loader new GLTFLoader(); loader.load( https://example.com/model.glb, (gltf) { const model gltf.scene; // 模型尺寸归一化避免不同美术导出比例差异导致画面空泛 const box new THREE.Box3().setFromObject(model); const size box.getSize(new THREE.Vector3()); const maxDim Math.max(size.x, size.y, size.z); const scale 10 / maxDim; model.scale.set(scale, scale, scale); scene.add(model); }, (progress) { // progress.total可能为0需要判空 if (progress.total 0) { const pct (progress.loaded / progress.total * 100).toFixed(0); console.log(加载进度: ${pct}%); } }, (error) { console.error(模型加载失败, error); // 降级处理加载一个简易几何体保证页面不空白 } );Box3.setFromObject是对模型做尺寸归一化的核心逻辑。不少模型导入后缩放在0.01或100这个量级相机距离如果按默认值设置模型要么占满屏幕裁剪掉要么小到看不见。我把最大边归一化到10个单位相机放在10到15的距离基本能保证大多数模型首次加载就出现在视野中心。加载进度回调里有个隐蔽的问题某些场景下progress.total是0比如本地包文件或特定网络环境。如果不判空loaded / total会得到Infinity进度显示直接变NaN。真机上的表现是模型正常加载但UI上的进度条一直卡在异常值需要刷新才正常。渲染循环是另一处容易出问题的地方。小程序的requestAnimationFrame频率和设备屏幕刷新率相关不能直接照搬浏览器的写法。适配层通常会把canvas.requestAnimationFrame暴露出来循环里做resize检查和render调用。整个循环放在onReady里启动后要记得在页面onHide和onUnload时中止。3.3 贴图路径、压缩纹理与编码问题GLB文件把贴图都塞在容器里加载路径问题最小。但有些美术提供的是GLTF外部贴图这种情况下小程序真机加载会因为相对路径解析失败而出现模型灰色无纹理。我在项目中遇到过两次类似情况最终都是让美术重新导出GLB。如果模型来源不可控代码层面唯一的兜底方案是在loader加载后遍历模型材质手动重设mapmodel.traverse((child) { if (child.isMesh child.material.map) { // 检查texture.image是否有效无效则说明纹理没加载成功 if (!child.material.map.image) { child.material.map fallbackTexture; child.material.needsUpdate true; } } });压缩纹理是另一个需要提前确认的坑。threejs支持KTX2、DDS这类压缩纹理格式可以显著降低显存占用但小程序的WebGL实现不一定支持对应的解码扩展。比如DDS依赖WEBGL_compress_texture_s3tc扩展而低端安卓机常常没有这个扩展。加载这类文件时控制台会静默失败模型不显示但没有任何报错。我的做法是统一要求导出方使用PNG或JPEG贴图并开启压缩而不是直接给GPU压缩纹理。如果真机内存压力大优先降低纹理分辨率而不是依赖GPU压缩格式。4. 常见问题与排查微信小程序threejs落地的5个高频坑适配版本能跑通不代表项目就稳了。下面这些坑基本是按出现频率排序前三个我在不同项目里都碰到过。4.1 模型加载后一片漆黑现象模型明明加载成功控制台没有报错但canvas上就是黑的或者只能看到剪影。原因场景没有任何灯光或者灯光设置不正确。threejs的材质默认行为里MeshStandardMaterial需要光源才能显示颜色没有光源时模型就是黑色剪影。开发者工具的模拟器有时会默认提供环境光背景一眼看过去是好的但到真机就露馅。解决检查场景中是否有AmbientLight和DirectionalLight不要只用单一环境光。经验值是环境光0.3到0.6强度平行光0.6到0.9两者叠加起来模型才有立体感。4.2 开发者工具显示正常真机上一片空白现象开发者工具里模型、光照、贴图都对预览到真机上却只有空白背景甚至连场景里的辅助网格都不显示。原因真机的WebGL实现和桌面差异很大最常见的是GPU精度不支持highp浮点数或者某些特性不支持。threejs默认会在部分手机上尝试使用highp一旦失败渲染管线就崩了。解决在renderer创建后强制设置精度renderer.setPixelRatio(Math.min(devicePixelRatio || 1, 2)); const gl renderer.getContext(); const precision gl.getShaderPrecisionFormat(gl.FRAGMENT_SHADER, gl.HIGH_FLOAT); if (precision precision.precision 0) { // 降级到mediump renderer.setPrecision(mediump); }另外部分安卓机的WebGL实现不完全支持threejs的某些扩展比如OES_element_index_uint。模型索引超过65535后这个扩展是必须的。真机上不支持时会出现模型变形或直接不渲染。排查方式很简单包一个返回当前WebGL extension列表的辅助函数打印到日志里对比。4.3 模型稍大包体直接超2MB现象把glb文件放进项目目录构建时提示主包超过2MB限制。原因小程序每个主包有体积限制模型文件动辄十几MB算上threejs适配层必然超限。解决把模型文件放到云存储或其他服务器上用URL加载。但这里有个必然关联的条件必须在后台配置合法的downloadFile域名否则真机load URL直接失败。开发阶段可以在开发者工具勾选“不校验合法域名”但这一步很容易忘记导致上线后模型全部加载不出来。我的习惯是在本地开发时就用固定测试域名而不是临时关掉校验。4.4 模型加载成功后切换页面内存暴涨现象从3D预览页返回列表页再重新进入预览页页面卡顿甚至直接闪退。原因页面销毁时只执行了wx.navigateBack但没有释放threejs的GPU资源。WebGLRenderer创建的纹理、缓冲区、program在页面卸载后仍然驻留在GPU内存里多次进出页面就会累积。解决在onUnload里显式释放onUnload() { this.renderer.dispose(); this.scene.traverse((obj) { if (obj.geometry) obj.geometry.dispose(); if (obj.material) { if (Array.isArray(obj.material)) { obj.material.forEach((m) m.dispose()); } else { obj.material.dispose(); } } }); this.canvas null; }dispose()这个方法很关键。Material.dispose()会释放着色器程序Geometry.dispose()释放缓冲区对象Renderer.dispose()释放关联默认资源。漏掉任何一个长时间驻留都是内存血崩的隐患。4.5 加载失败没有提示页面一直白屏现象网络请求失败或模型文件损坏时页面长时间显示Loading旋转图标一直转。原因GLTFLoader.load的onError回调里没有处理逻辑用户得不到任何反馈。加载过程也没有超时逻辑请求挂死的时候Loading永远不消失。解决设置一个超时定时器比如15秒未完成就判定失败并展示降级UI。同时onError里打印error对象中的statusCode和errMsg。真机上最常见的错误码是downloadFile:fail url not in domain list这个错误码出来基本可以确定是域名白名单漏配了。5. 性能验证与优化从能显示到值得上线模型能显示之后下一步是验证它是否值得上线。我的验证方法是在渲染循环里打点统计帧率在真机上观察30秒。用代码把帧率显示在canvas角落比任何性能面板都直观let frames 0; let lastTime Date.now(); function render() { frames; const now Date.now(); if (now - lastTime 1000) { console.log(FPS: ${frames}); frames 0; lastTime now; } renderer.render(scene, camera); canvas.requestAnimationFrame(render); }真机帧率稳定在30以上这个方案基本可交付如果连20都到不了先砍渲染分辨率。把renderer.setPixelRatio从2降到1再设置renderer.setSize为屏幕物理宽度的一半视觉影响通常不大帧率提升却非常明显。低端安卓机上这一步通常能救回10帧以上。优化优先级上先看模型三角面数。一个glb文件里如果有超过20万面的模型小程序的CPU和GPU都很难扛住。我会在加载后打印model.children.length和每个mesh.geometry.attributes.position.count对模型面数做到心里有数。贴图分辨率的优先级其次2048以上的贴图很多真机会出现纹理闪烁降到1024或512显存占用直接成倍下降。画质和性能的取舍上我的习惯是保留环境光和主方向光两个光源不开阴影。阴影在小程序threejs中的计算成本很高一旦开启帧率直接对半。如果要展示精细度用相机近裁剪面吃细节比开阴影更值得。另外一个常用技巧是模型缩放后再处理动画如果模型带骨骼动画优先确认动画时长和循环方式避免渲染循环里每帧都触发大范围的矩阵运算。最后分享一个我的固定习惯加载失败的模型日志里记录一次错误信息页面降级显示为简易几何体或静态图不让用户看到白屏。这个习惯帮我抓到了很多资源格式问题也让项目在真实网络环境下不至于完全不可用。希望这一套排查和优化思路能帮你在小程序3D展示这条路上少熬几个夜。本文还有配套的精品资源点击获取