简介面向微信小程序开发者与前端学习者的 three.js 外部 3D 模型加载实践包聚焦小程序环境缺少直接 npm 依赖、模型资源接入链路较长这一常见难点适合具备 JavaScript 基础、希望补齐三维渲染能力的中级开发者。压缩包共 11 个文件大小约 167KB其中 4 个 js 脚本承担 three.js 接入、模型加载与渲染逻辑4 个 json 配置用于小程序项目与页面注册另含 1 个 md 说明、1 个 wxss 样式和 1 个 wxml 页面结构整体按页面、库文件与加载器分层组织。已有 3208 人学习说明该主题在小程序 3D 场景搭建中关注度较高。读者可据此参考场景、相机、渲染器的初始化方式了解外部模型加载、动画循环、触摸事件坐标转换及资源释放的代码组织也能借助说明文档和配置结构排查模型格式、网络请求、视口适配与性能限制等问题。1. 微信小程序里跑 Three.js真正难的从来不是 Three.js去年接了个小需求在微信小程序里放一个能用手势旋转的产品 3D 模型替掉原来六张静态图的轮播。做 H5 的同事第一反应是把 Three.js 那套场景整个搬过来——本地浏览器里跑得好好的代码进小程序不到十分钟就翻车document是 undefinedcanvas拿不到 DOM 节点加载器内部的XMLHttpRequest压根不存在。这个示例工程就是把这条路重新走通的产物用 JavaScript 在小程序里接上 Three.js 的渲染管线再从 CDN 拉 glb 模型解析上屏。它适合两类人需要在商品详情、课程演示、线上展厅里放可交互 3D 内容的前端以及想弄清小程序 WebGL 边界到底在哪、不想再被真机黑屏反复折磨的人。2. 工程结构与适配层threejs-miniprogram 怎么把 Three.js 塞进小程序2.1 目录结构一个渲染页加一份裁剪过的 Three这种项目不会做得很重通常就是「一个页面把所有 3D 逻辑跑通」外部依赖单独放一个目录方便和业务代码隔离。第一次拉下来先看骨架比直接翻业务逻辑有效得多miniprogramThree/ ├── app.js # 全局只做一件事初始化日志与全局错误捕获 ├── app.json # 页面注册、窗口配置 ├── project.config.json # 开发者工具项目配置注意 appid 与编译设置 ├── libs/ │ ├── threejs-miniprogram/ # 适配版 Three导出一个 createScopedThreejs │ │ ├── index.js │ │ └── three.weapp.js # 裁剪后的核心库体积比完整版小一截 │ └── GLTFLoader.js # 模型加载器工厂函数式导出需注入 THREE └── pages/ └── scene/ ├── scene.js # 页面逻辑初始化、加载、渲染循环、交互 ├── scene.json # 单页配置通常设 navigationStyle └── scene.wxml # 一个 typewebgl 的 canvaslibs单独拎出来的好处是升级 Three 版本时只动一个地方页面里始终只依赖createScopedThreejs和GLTFLoader两个入口。常见做法是把GLTFLoader.js也一起放进libs而不是从 npm 装完整包再 tree-shaking因为小程序侧的node_modules构建链路对 Three 这种体量的库并不友好构建耗时和包体积都不划算。scene.wxml里只有一个节点但属性不能少!-- pages/scene/scene.wxml -- canvas typewebgl idwebgl stylewidth: 100vw; height: 100vh; display: block; bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd /canvastypewebgl是硬性要求不加这个属性拿到的就是 2D 上下文。id要和后面SelectorQuery里的选择器一致。手势事件直接绑在 canvas 上不要用外层view包一层再监听否则手指移出 canvas 边界时事件会断旋转到一半停住的手感非常差。2.2 适配层做了什么把 document、window 这些缺口补上Three.js 的核心是纯数学加 WebGL 调用理论上是能在任何有 WebGL 上下文的环境里跑的。真正卡住它的是那些外围设施WebGLRenderer要往 DOM 里插 canvasTextureLoader要new Image()FileLoader用XMLHttpRequest还有window.devicePixelRatio、document.createElement(canvas)这些。小程序运行环境里一个都没有。threejs-miniprogram干的事情就是给这些缺口做替换把 canvas 节点直接喂给渲染器把图片加载换成canvas.createImage()把文件加载的活儿交给开发者自己用wx.request干。它导出的不是完整的THREE而是一个工厂// pages/scene/scene.js const { createScopedThreejs } require(../../libs/threejs-miniprogram/index.js) // canvas 是 SelectorQuery 拿到的节点 const THREE createScopedThreejs(canvas)这个名字里的Scoped是关键。每调一次返回的是一套绑定到这块 canvas 上的、相互隔离的 Three 命名空间。听起来有点绕但实际意义很直接一个页面里如果有多块 3D 画布各自拿到的THREE不共享内部状态不会出现一个渲染器把另一个的纹理上下文搞乱的情况。代价是不能全局缓存一份 THREE 到处用必须按 canvas 维度持有。提示createScopedThreejs返回的对象上和官方 Three 文档里的 API 基本对齐但版本越老缺的东西越多比如某些后期处理模块、DRACOLoader之类往往需要自己另找适配版。动手前先在控制台打印一下Object.keys(THREE)比对着文档猜要快。2.3 依赖引入的两种方式与版本对齐引入适配库有两条路。一条是从 npm 安装后走开发者工具的「构建 npm」另一条是直接把编译产物拷进libs。前者适合团队协作、要锁版本的场景后者适合快速验证也避免构建产物在不同工具版本下行为不一致。// project.config.json 中与构建相关的片段 { setting: { es6: true, enhance: true, minified: true, packNpmManually: true, packNpmRelationList: [ { packageJsonPath: ./package.json, miniprogramNpmDistDir: ./miniprogram/ } ] } }es6和enhance必须开Three 源码里大量使用class、扩展运算符、可选链关掉之后编译阶段就报语法错错误信息还指向压缩后的行号排查起来很费劲。packNpmManually配合packNpmRelationList是为了把 npm 依赖产出到指定目录多人协作时不至于每个人的构建产物路径都不一样。版本上有个血泪经验Three 主库和 GLTFLoader 必须同源。适配库通常是对某个具体 Three 版本打的补丁你从别处拷一个更新版的GLTFLoader.js进来它内部调用的THREE.BufferGeometry新方法在旧核心里不存在表现是模型加载到一半 Promise 永远不 resolve控制台干干净净什么都不报。我一般会在libs下放一个VERSION.md记清楚每个文件对应的上游版本号升级时一起换。3. 场景初始化从 canvas 节点到第一帧画面3.1 SelectorQuery 取节点把画布尺寸一次算对小程序里所有 DOM 操作都被替换成了SelectorQuery而且拿 canvas 节点还得用.node()普通.select()拿到的只是个描述对象没有getContext。整个初始化链路是这样的// pages/scene/scene.js Page({ data: {}, onReady() { this.initCanvas() }, initCanvas() { wx.createSelectorQuery() .in(this) // 限定在当前页面内查询 .select(#webgl) .node() // 关键取真实节点而不是快照 .exec((res) { if (!res || !res[0] || !res[0].node) { console.error(canvas 节点获取失败检查 id 与 type) return } this.canvas res[0].node this.THREE createScopedThreejs(this.canvas) this.initScene() this.loadModel() this.startLoop() }) } }).in(this)很多人会漏。页面栈里有多个页面时不加限定的查询可能命中上一个页面的节点拿到的 canvas 早就被销毁了后面所有渲染都往一块死画布上画真机表现为白屏开发者工具里反而正常——这个差异我踩过不止一次。尺寸计算要一次到位不然后面全是连锁问题initScene() { const THREE this.THREE const canvas this.canvas const sys wx.getSystemInfoSync() const dpr sys.pixelRatio || 2 // canvas 的 width/height 是像素值style 里的是 CSS 尺寸两者要分开算 canvas.width sys.windowWidth * dpr canvas.height sys.windowHeight * dpr const renderer new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false }) // 尺寸已经手动乘过 dpr这里必须置 1否则会被再乘一遍 renderer.setPixelRatio(1) renderer.setSize(sys.windowWidth * dpr, sys.windowHeight * dpr, false) this.renderer renderer this.screenWidth sys.windowWidth this.screenHeight sys.windowHeight this.initCameraAndLight() }这里setPixelRatio(1)那行是整个初始化里最容易翻车的地方。WebGLRenderer的默认逻辑是「尺寸 setSize 传入值 × pixelRatio」而小程序的 canvas 不像浏览器那样有 CSS 尺寸兜底它认的就是canvas.width这个原始属性。两个都乘 dpr 的结果是画布实际缓冲区变成四倍大画面只占左下角四分之一剩下的全是背景色。参数上antialias建议开模型边缘的锯齿在手机小屏上非常明显alpha: false能省一点合成开销除非你要让 3D 内容叠在页面元素下面。3.2 相机、光照与背景的三件套场景本身没什么可讲的new THREE.Scene()就完事。真正影响观感的是相机参数和光照配置外行看是「模型亮不亮」内行看是材质和光源类型对不上。initCameraAndLight() { const THREE this.THREE const aspect this.screenWidth / this.screenHeight const scene new THREE.Scene() scene.background new THREE.Color(0xf2f3f5) this.scene scene // 45 度视场角是移动端的常用值太大透视畸变明显太小模型显得扁平 const camera new THREE.PerspectiveCamera(45, aspect, 0.1, 1000) camera.position.set(0, 0, 5) camera.lookAt(0, 0, 0) this.camera camera // 环境光打底避免背光面全黑 const ambient new THREE.AmbientLight(0xffffff, 0.85) scene.add(ambient) // 主光源给体积感和高光 const key new THREE.DirectionalLight(0xffffff, 1.0) key.position.set(3, 5, 4) scene.add(key) // 补光压暗部强度控制在主光的三分之一左右 const fill new THREE.DirectionalLight(0xffffff, 0.35) fill.position.set(-4, -2, -3) scene.add(fill) }参数上值得说的是near和far。写0.1 / 1000是图省事但如果模型本身尺寸很小比如一个几厘米的零件near太大会导致近处被裁掉模型很大比如一栋楼far太小会导致远处消失。这两个值后面在相机自适应那一步会跟着模型尺寸重算这里先给个安全范围。光照强度单位在不同 Three 版本里有变化老版本是简单的倍数新版本引入了物理光照单位同样的1.0在两个版本下亮度能差一倍。如果你发现模型在开发者工具里正常、真机上过曝或者发灰先查版本别急着调参数——这是我见过最多人浪费时间的地方。3.3 渲染循环替掉 window.requestAnimationFrame浏览器里用window.requestAnimationFrame小程序里没有这个全局方法但 canvas 节点自带了同名方法。注意是节点上的方法不是wx.开头的 APIstartLoop() { const loop () { // 用 canvas 的方法续帧返回值用于后续取消 this.rafId this.canvas.requestAnimationFrame(loop) // 简易节流不追求 60 帧30 帧对展示类场景足够 const now Date.now() if (now - (this.lastFrameTime || 0) 33) return this.lastFrameTime now if (this.model this.autoRotate) { this.model.rotation.y 0.008 } this.renderer.render(this.scene, this.camera) } loop() }, stopLoop() { if (this.rafId this.canvas) { this.canvas.cancelAnimationFrame(this.rafId) this.rafId null } }节流那段不是可有可无的优化。中低端安卓机上一个中等面数的 glb 模型跑满 60 帧GPU 占用会飙到很高手机会明显发热用户切后台再回来就发现页面卡成 PPT。压到 30 帧肉眼几乎看不出差别功耗能降将近一半。33这个数是 1000/30 取整想要 24 帧就改成 41。更关键的是必须能停下来。页面隐藏、跳转、卸载时不停循环requestAnimationFrame 会一直排队渲染器持续往一块已经不可见的画布上绘制内存和 GPU 资源都不释放。反复进出同一个页面五六次内存就能翻倍。onHide() { this.stopLoop() }, onUnload() { this.stopLoop() this.disposeAll() }, onShow() { // 回到前台重新起循环注意别重复 start 造成多路循环 if (!this.rafId this.renderer) { this.startLoop() } }onShow里那个if (!this.rafId)判断很有必要。如果onHide因为某种原因没触发比如页面被系统回收再startLoop就会同时跑两条循环帧率翻倍功耗翻倍模型转速也翻倍看起来像「转得特别快」的玄学 bug。4. 外部模型加载GLTFLoader 解析链路的改造4.1 load(url) 走不通的原因拿到GLTFLoader之后本能反应是照着文档写loader.load(url, onLoad)。这段代码在小程序里跑起来不会报错回调也永远不会触发控制台一片安静。原因在FileLoader内部。它做三件事创建XMLHttpRequest、监听progress事件、把响应按arraybuffer或text取出来。小程序没有XMLHttpRequest适配层一般会塞一个极简 shim 进去让它别崩但这个 shim 只保证不抛异常不保证真的发请求。于是 loader 一直等一个永远不来的响应。glb是二进制格式.gltf是 JSON两者最终都归一成parse(arrayBuffer | json, path, onLoad, onError)。既然网络请求这层小程序有能力自己做那就把请求和解析拆开wx.request负责拉数据loader.parse负责解析。这是所有小程序 3D 项目绕不开的一步。4.2 wx.request 拉二进制 loader.parseloadModel() { const THREE this.THREE const url https://cdn.example.com/models/robot.glb wx.showLoading({ title: 模型加载中, mask: true }) wx.request({ url, method: GET, responseType: arraybuffer, // 必须是这个默认是 text 会直接损坏二进制 timeout: 20000, success: (res) { if (res.statusCode ! 200) { wx.hideLoading() wx.showToast({ title: HTTP ${res.statusCode}, icon: none }) return } this.parseModel(res.data) }, fail: (err) { wx.hideLoading() console.error(模型下载失败, err) wx.showToast({ title: 下载失败, icon: none }) } }) }, parseModel(buffer) { const THREE this.THREE // 工厂函数式引入把 scoped THREE 注入进去 const GLTFLoader require(../../libs/GLTFLoader.js)(THREE) const loader new GLTFLoader() // 第二个参数是资源根路径glb 内部自带贴图时可以传空字符串 loader.parse(buffer, , (gltf) { wx.hideLoading() const model gltf.scene this.fitCamera(model) this.scene.add(model) this.model model }, (err) { wx.hideLoading() console.error(模型解析失败, err) wx.showToast({ title: 解析失败, icon: none }) }) }responseType: arraybuffer是这段代码里唯一的硬性参数写错成默认值text拿到的是一个被 UTF-8 解码破坏过的字符串loader.parse会在读取文件头 magic number 的时候直接抛异常报错信息大概是「Unsupported glTF-Binary header」看起来像是模型文件坏了其实是请求参数的问题。loader.parse的第二个参数path决定相对路径资源的解析基准。纯glb贴图、几何全内嵌传空串就行如果是.gltf.bin 一堆.png的分离结构这里要传模型所在目录的完整 URL末尾带斜杠。传错的后果是贴图静默丢失模型变成灰色——不报错只是加载器把纹理请求发出去了但取不回来。注意wx.request要求域名在白名单里。开发阶段可以在开发者工具里勾「不校验合法域名」真机预览时必须配好业务域名否则请求直接 fail且错误码被合并成笼统的request:fail看不出具体原因。4.3 贴图加载canvas.createImage 替代 new Imageglb内嵌贴图的话上面那段代码就能跑出完整效果。一旦碰到外链贴图就得自己接管图片加载。TextureLoader内部走的是new Image()小程序里没有这个构造函数替代品是canvas.createImage()// 通用纹理加载先拿到可用的本地路径再喂给图片对象 function loadTexture(canvas, THREE, remoteUrl) { return new Promise((resolve, reject) { // 网络图片先走 getImageInfo 拿临时路径否则 img.src 直接赋 URL 可能失败 wx.getImageInfo({ src: remoteUrl, success: (info) { const img canvas.createImage() img.onload () { const texture new THREE.Texture(img) texture.needsUpdate true // 手动构造的纹理必须显式标记 resolve(texture) } img.onerror () reject(new Error(图片解码失败: remoteUrl)) img.src info.path }, fail: reject }) }) }用的时候是在模型加载完成之后遍历材质把map换掉loadExternalTextures(model, textureUrl) { loadTexture(this.canvas, this.THREE, textureUrl).then((texture) { model.traverse((child) { if (!child.isMesh || !child.material) return const mats Array.isArray(child.material) ? child.material : [child.material] mats.forEach((mat) { if (mat.map) mat.map.dispose() // 先释放旧的避免显存叠加 mat.map texture mat.needsUpdate true // 材质参数变了必须重新编译 }) }) }).catch((err) console.error(贴图替换失败, err)) }texture.needsUpdate true和mat.needsUpdate true这两个标记缺一不可。前者告诉渲染器这张纹理还没上传过 GPU后者告诉渲染器着色器需要重新编译。少任何一个的表现都是「模型有颜色但贴图不显示」而且不报任何错属于典型的黑匣子问题。颜色空间还有个小坑模型的贴图通常是 sRGB渲染器的输出也要设成对应的编码否则整体会偏暗或者发灰。老版本里是renderer.outputEncoding THREE.sRGBEncoding新版本换成了renderer.outputColorSpace THREE.SRGBColorSpace具体用哪个看你手上这版 THREE 暴露了什么。4.4 包围盒自适应模型大小不一也不用手动调相机从外面拿到的模型单位可能是米、厘米、毫米原点可能在几何中心也可能在脚底。写死camera.position.set(0, 0, 5)的结果是有的模型糊在脸上有的模型只剩一个小点。正确做法是加载完成后算包围盒按尺寸反推相机距离顺便把模型挪到原点这样旋转手势才是绕自身中心转fitCamera(object) { const THREE this.THREE const box new THREE.Box3().setFromObject(object) const size box.getSize(new THREE.Vector3()) const center box.getCenter(new THREE.Vector3()) // 平移模型让它围绕原点旋转 object.position.sub(center) object.position.y size.y / 2 // 需要落地感时把底面对齐到 y0 const maxSize Math.max(size.x, size.y, size.z) const fovRad (this.camera.fov * Math.PI) / 180 // 由视场角和模型最大边长反推最小可视距离 const distance (maxSize / 2) / Math.tan(fovRad / 2) this.camera.position.set(0, size.y * 0.3, distance * 1.4) this.camera.near distance / 100 this.camera.far distance * 100 this.camera.lookAt(0, 0, 0) this.camera.updateProjectionMatrix() // 改了 near/far 必须手动更新投影矩阵 // 记录初始距离供手势缩放时做上下限约束 this.baseDistance distance * 1.4 }1.4这个系数是留白让模型四周有点呼吸空间压到1.1会显得很挤放到2.0又太小。camera.position.y用size.y * 0.3是个折中纯俯视太平纯平视又看不到顶面结构。updateProjectionMatrix()那行漏掉的概率极高。near和far是相机投影矩阵的组成部分改了属性不调用这个方法渲染器还用旧矩阵表现是近处被裁掉一块或者远处消失而且不管你怎么调参数都没反应。5. 踩坑排查真机黑屏、贴图丢失和内存不回收5.1 开发者工具正常真机白屏现象工具里模型转得好好的扫码真机预览一片白控制台没有任何 WebGL 相关报错。原因九成是画布尺寸问题。前面提到canvas.width和setSize都乘了 dpr实际缓冲区被放到四倍大超出部分直接空白另一种情况是SelectorQuery没加.in(this)取到的是上一个页面残留的节点。解决先把canvas.width/canvas.height/renderer.getSize()三个值打到日志里对一遍正常情况下前两个相等第三个是它们的值。再确认setPixelRatio(1)。真机调试时打开「vConsole」看实时日志比在开发者工具里猜快得多。5.2 模型上屏但是全黑或者只剩剪影现象加载成功、scene.children里能看到模型画面却完全没有材质细节。原因材质是MeshStandardMaterial或MeshPhysicalMaterial这两种材质完全依赖光源没有光照就是纯黑。另外模型自带的KHR_materials_*扩展在旧版加载器里不被识别会被降级成默认灰色材质。解决先补一盏AmbientLight打底强度给到0.6以上再检查控制台有没有「Unknown extension」之类的警告有的话要么升级加载器要么在loader.parse之后遍历材质手动设MeshBasicMaterial兜底。展示类场景用基础材质反而更可控不必强求物理材质。5.3 贴图丢失模型整体发灰现象几何形状完全正确但表面是单一灰色没有任何图案。原因分离式 glTF 的贴图路径解析失败。loader.parse的path参数传了空串或者传了页面相对路径加载器拼出来的图片地址是错的请求失败后被静默吞掉。另一种可能是blob:协议的 URL 在小程序里根本不可用。解决优先让美术导出一个内嵌贴图的.glb文件大一点但省掉整条路径解析链路。实在要用外链就按 4.3 的做法自己接管纹理加载加载完成后按材质名精确替换别指望加载器自动搞定。5.4 页面来回进出几次就卡死现象第一次进页面流畅进出三五次之后明显卡顿最终白屏或者小程序直接闪退。原因requestAnimationFrame没有取消渲染循环在后台一直跑同时几何体、材质、纹理的 GPU 资源没有dispose每进一次页面就泄漏一份。解决onHide停循环onUnload停循环并执行完整清理。清理要递归遍历disposeAll() { if (this.model) { this.model.traverse((child) { if (child.geometry) child.geometry.dispose() if (!child.material) return const mats Array.isArray(child.material) ? child.material : [child.material] mats.forEach((mat) { // 材质上的每一张纹理都要单独释放 Object.keys(mat).forEach((key) { const val mat[key] if (val val.isTexture) val.dispose() }) mat.dispose() }) }) this.scene.remove(this.model) this.model null } if (this.renderer) { this.renderer.dispose() this.renderer null } }isTexture判断比写死mat.map.dispose()稳因为一个材质可能同时挂了map、normalMap、roughnessMap好几张纹理只释放主贴图等于没清理。5.5 手势旋转一顿一顿的现象手指滑动时模型转动不跟手有延迟感。原因touchmove里直接改了rotation但渲染循环是 30 帧节流事件频率远高于渲染频率中间大量计算被丢弃或者touchmove触发了setData页面逻辑层和渲染层通信开销把主线程堵住了。解决touchmove里只更新旋转缓存值真正的赋值放在渲染循环里做整个交互链路里一次setData都不要调。3D 场景的所有状态都放this上data只用于驱动 WXML 里那几个无关紧要的文案。6. 二次开发从能看会转到性能兜底的改造清单模型能转起来只是起点真正交付前还得过几关。下面这几条是我在这个工程上反复改过的地方按优先级排改造方向具体改动需要留意的地方手势交互单指旋转 双指捏合缩放缩放要基于baseDistance做上下限别让用户把相机推进模型内部自动旋转无操作 2 秒后恢复自转用定时器记录最后交互时间touchstart里重置性能兜底低端机降帧、降 pixelRatiowx.getDeviceInfo拿机型档位中低端直接把 dpr 压到 1.5模型预加载上一个页面空闲时提前wx.request把 arraybuffer 缓存到全局进页面直接parse省掉等待多模型切换保留 renderer只换 model切换时先dispose旧的再加载新的避免显存翻倍双指缩放的实现比旋转麻烦一点核心是记录两个触点的距离变化onTouchMove(e) { if (!this.model) return if (e.touches.length 2) { // 双指算两点间距和上一次比得出缩放系数 const dx e.touches[0].clientX - e.touches[1].clientX const dy e.touches[0].clientY - e.touches[1].clientY const dist Math.sqrt(dx * dx dy * dy) if (this.lastPinch) { const scale dist / this.lastPinch const next this.camera.position.z / scale // 约束在基准距离的 0.5 到 2 倍之间 const min this.baseDistance * 0.5 const max this.baseDistance * 2 this.camera.position.z Math.min(max, Math.max(min, next)) this.camera.lookAt(0, 0, 0) } this.lastPinch dist this.lastTouchTime Date.now() return } // 单指只更新缓存渲染循环里统一应用 const t e.touches[0] if (this.lastX ! null) { this.pendingRotY (this.pendingRotY || 0) (t.clientX - this.lastX) * 0.01 this.pendingRotX (this.pendingRotX || 0) (t.clientY - this.lastY) * 0.01 } this.lastX t.clientX this.lastY t.clientY this.lastTouchTime Date.now() }pendingRotX和pendingRotY这两块缓存是「跟手」的关键渲染循环里再一次性累加到model.rotation上。如果直接在事件回调里改rotation30 帧节流会让手指的位移被丢掉大半手感就变成了「划半天转一点」。切换模型那段也有个容易忽略的点新的模型加载完成之前旧的不能删。常见做法是先把新模型的arraybuffer请求发出去success回调里再执行「移除旧的 → 解析新的 → 加到场景」这样界面中间会有一小段空白但不会闪。如果反过来先删后加载网络慢的时候用户看到的就是纯背景色体感很差。关于低端机降级我的做法是在初始化阶段读一次设备信息const info wx.getDeviceInfo() // benchmarkLevel 是微信给的整机性能参考值越低越吃力 const isLowEnd info.benchmarkLevel ! null info.benchmarkLevel 10 const dpr isLowEnd ? 1 : (wx.getSystemInfoSync().pixelRatio || 2)benchmarkLevel这个值不是所有机型都有拿不到时按中端处理。低端机上把 dpr 压到 1画面会糊一点但好歹能转起来高分辨率配卡顿的体验比低分辨率流畅要差得多。最后说个习惯。这个项目之后我每次做小程序 3D都会先写一个最小验证页一块 canvas、一个立方体、一盏灯、一个循环别的什么都不加。这段代码能在这个机型上跑出画面才说明适配层、尺寸计算、渲染循环这三层是通的再往上堆模型和交互。跳过这一步直接上真实模型出问题时你分不清是环境没搭好还是模型有问题排查成本翻好几倍。希望帮到你。本文还有配套的精品资源点击获取
简介面向微信小程序开发者与前端学习者的 three.js 外部 3D 模型加载实践包聚焦小程序环境缺少直接 npm 依赖、模型资源接入链路较长这一常见难点适合具备 JavaScript 基础、希望补齐三维渲染能力的中级开发者。压缩包共 11 个文件大小约 167KB其中 4 个 js 脚本承担 three.js 接入、模型加载与渲染逻辑4 个 json 配置用于小程序项目与页面注册另含 1 个 md 说明、1 个 wxss 样式和 1 个 wxml 页面结构整体按页面、库文件与加载器分层组织。已有 3208 人学习说明该主题在小程序 3D 场景搭建中关注度较高。读者可据此参考场景、相机、渲染器的初始化方式了解外部模型加载、动画循环、触摸事件坐标转换及资源释放的代码组织也能借助说明文档和配置结构排查模型格式、网络请求、视口适配与性能限制等问题。1. 微信小程序里跑 Three.js真正难的从来不是 Three.js去年接了个小需求在微信小程序里放一个能用手势旋转的产品 3D 模型替掉原来六张静态图的轮播。做 H5 的同事第一反应是把 Three.js 那套场景整个搬过来——本地浏览器里跑得好好的代码进小程序不到十分钟就翻车document是 undefinedcanvas拿不到 DOM 节点加载器内部的XMLHttpRequest压根不存在。这个示例工程就是把这条路重新走通的产物用 JavaScript 在小程序里接上 Three.js 的渲染管线再从 CDN 拉 glb 模型解析上屏。它适合两类人需要在商品详情、课程演示、线上展厅里放可交互 3D 内容的前端以及想弄清小程序 WebGL 边界到底在哪、不想再被真机黑屏反复折磨的人。2. 工程结构与适配层threejs-miniprogram 怎么把 Three.js 塞进小程序2.1 目录结构一个渲染页加一份裁剪过的 Three这种项目不会做得很重通常就是「一个页面把所有 3D 逻辑跑通」外部依赖单独放一个目录方便和业务代码隔离。第一次拉下来先看骨架比直接翻业务逻辑有效得多miniprogramThree/ ├── app.js # 全局只做一件事初始化日志与全局错误捕获 ├── app.json # 页面注册、窗口配置 ├── project.config.json # 开发者工具项目配置注意 appid 与编译设置 ├── libs/ │ ├── threejs-miniprogram/ # 适配版 Three导出一个 createScopedThreejs │ │ ├── index.js │ │ └── three.weapp.js # 裁剪后的核心库体积比完整版小一截 │ └── GLTFLoader.js # 模型加载器工厂函数式导出需注入 THREE └── pages/ └── scene/ ├── scene.js # 页面逻辑初始化、加载、渲染循环、交互 ├── scene.json # 单页配置通常设 navigationStyle └── scene.wxml # 一个 typewebgl 的 canvaslibs单独拎出来的好处是升级 Three 版本时只动一个地方页面里始终只依赖createScopedThreejs和GLTFLoader两个入口。常见做法是把GLTFLoader.js也一起放进libs而不是从 npm 装完整包再 tree-shaking因为小程序侧的node_modules构建链路对 Three 这种体量的库并不友好构建耗时和包体积都不划算。scene.wxml里只有一个节点但属性不能少!-- pages/scene/scene.wxml -- canvas typewebgl idwebgl stylewidth: 100vw; height: 100vh; display: block; bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd /canvastypewebgl是硬性要求不加这个属性拿到的就是 2D 上下文。id要和后面SelectorQuery里的选择器一致。手势事件直接绑在 canvas 上不要用外层view包一层再监听否则手指移出 canvas 边界时事件会断旋转到一半停住的手感非常差。2.2 适配层做了什么把 document、window 这些缺口补上Three.js 的核心是纯数学加 WebGL 调用理论上是能在任何有 WebGL 上下文的环境里跑的。真正卡住它的是那些外围设施WebGLRenderer要往 DOM 里插 canvasTextureLoader要new Image()FileLoader用XMLHttpRequest还有window.devicePixelRatio、document.createElement(canvas)这些。小程序运行环境里一个都没有。threejs-miniprogram干的事情就是给这些缺口做替换把 canvas 节点直接喂给渲染器把图片加载换成canvas.createImage()把文件加载的活儿交给开发者自己用wx.request干。它导出的不是完整的THREE而是一个工厂// pages/scene/scene.js const { createScopedThreejs } require(../../libs/threejs-miniprogram/index.js) // canvas 是 SelectorQuery 拿到的节点 const THREE createScopedThreejs(canvas)这个名字里的Scoped是关键。每调一次返回的是一套绑定到这块 canvas 上的、相互隔离的 Three 命名空间。听起来有点绕但实际意义很直接一个页面里如果有多块 3D 画布各自拿到的THREE不共享内部状态不会出现一个渲染器把另一个的纹理上下文搞乱的情况。代价是不能全局缓存一份 THREE 到处用必须按 canvas 维度持有。提示createScopedThreejs返回的对象上和官方 Three 文档里的 API 基本对齐但版本越老缺的东西越多比如某些后期处理模块、DRACOLoader之类往往需要自己另找适配版。动手前先在控制台打印一下Object.keys(THREE)比对着文档猜要快。2.3 依赖引入的两种方式与版本对齐引入适配库有两条路。一条是从 npm 安装后走开发者工具的「构建 npm」另一条是直接把编译产物拷进libs。前者适合团队协作、要锁版本的场景后者适合快速验证也避免构建产物在不同工具版本下行为不一致。// project.config.json 中与构建相关的片段 { setting: { es6: true, enhance: true, minified: true, packNpmManually: true, packNpmRelationList: [ { packageJsonPath: ./package.json, miniprogramNpmDistDir: ./miniprogram/ } ] } }es6和enhance必须开Three 源码里大量使用class、扩展运算符、可选链关掉之后编译阶段就报语法错错误信息还指向压缩后的行号排查起来很费劲。packNpmManually配合packNpmRelationList是为了把 npm 依赖产出到指定目录多人协作时不至于每个人的构建产物路径都不一样。版本上有个血泪经验Three 主库和 GLTFLoader 必须同源。适配库通常是对某个具体 Three 版本打的补丁你从别处拷一个更新版的GLTFLoader.js进来它内部调用的THREE.BufferGeometry新方法在旧核心里不存在表现是模型加载到一半 Promise 永远不 resolve控制台干干净净什么都不报。我一般会在libs下放一个VERSION.md记清楚每个文件对应的上游版本号升级时一起换。3. 场景初始化从 canvas 节点到第一帧画面3.1 SelectorQuery 取节点把画布尺寸一次算对小程序里所有 DOM 操作都被替换成了SelectorQuery而且拿 canvas 节点还得用.node()普通.select()拿到的只是个描述对象没有getContext。整个初始化链路是这样的// pages/scene/scene.js Page({ data: {}, onReady() { this.initCanvas() }, initCanvas() { wx.createSelectorQuery() .in(this) // 限定在当前页面内查询 .select(#webgl) .node() // 关键取真实节点而不是快照 .exec((res) { if (!res || !res[0] || !res[0].node) { console.error(canvas 节点获取失败检查 id 与 type) return } this.canvas res[0].node this.THREE createScopedThreejs(this.canvas) this.initScene() this.loadModel() this.startLoop() }) } }).in(this)很多人会漏。页面栈里有多个页面时不加限定的查询可能命中上一个页面的节点拿到的 canvas 早就被销毁了后面所有渲染都往一块死画布上画真机表现为白屏开发者工具里反而正常——这个差异我踩过不止一次。尺寸计算要一次到位不然后面全是连锁问题initScene() { const THREE this.THREE const canvas this.canvas const sys wx.getSystemInfoSync() const dpr sys.pixelRatio || 2 // canvas 的 width/height 是像素值style 里的是 CSS 尺寸两者要分开算 canvas.width sys.windowWidth * dpr canvas.height sys.windowHeight * dpr const renderer new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false }) // 尺寸已经手动乘过 dpr这里必须置 1否则会被再乘一遍 renderer.setPixelRatio(1) renderer.setSize(sys.windowWidth * dpr, sys.windowHeight * dpr, false) this.renderer renderer this.screenWidth sys.windowWidth this.screenHeight sys.windowHeight this.initCameraAndLight() }这里setPixelRatio(1)那行是整个初始化里最容易翻车的地方。WebGLRenderer的默认逻辑是「尺寸 setSize 传入值 × pixelRatio」而小程序的 canvas 不像浏览器那样有 CSS 尺寸兜底它认的就是canvas.width这个原始属性。两个都乘 dpr 的结果是画布实际缓冲区变成四倍大画面只占左下角四分之一剩下的全是背景色。参数上antialias建议开模型边缘的锯齿在手机小屏上非常明显alpha: false能省一点合成开销除非你要让 3D 内容叠在页面元素下面。3.2 相机、光照与背景的三件套场景本身没什么可讲的new THREE.Scene()就完事。真正影响观感的是相机参数和光照配置外行看是「模型亮不亮」内行看是材质和光源类型对不上。initCameraAndLight() { const THREE this.THREE const aspect this.screenWidth / this.screenHeight const scene new THREE.Scene() scene.background new THREE.Color(0xf2f3f5) this.scene scene // 45 度视场角是移动端的常用值太大透视畸变明显太小模型显得扁平 const camera new THREE.PerspectiveCamera(45, aspect, 0.1, 1000) camera.position.set(0, 0, 5) camera.lookAt(0, 0, 0) this.camera camera // 环境光打底避免背光面全黑 const ambient new THREE.AmbientLight(0xffffff, 0.85) scene.add(ambient) // 主光源给体积感和高光 const key new THREE.DirectionalLight(0xffffff, 1.0) key.position.set(3, 5, 4) scene.add(key) // 补光压暗部强度控制在主光的三分之一左右 const fill new THREE.DirectionalLight(0xffffff, 0.35) fill.position.set(-4, -2, -3) scene.add(fill) }参数上值得说的是near和far。写0.1 / 1000是图省事但如果模型本身尺寸很小比如一个几厘米的零件near太大会导致近处被裁掉模型很大比如一栋楼far太小会导致远处消失。这两个值后面在相机自适应那一步会跟着模型尺寸重算这里先给个安全范围。光照强度单位在不同 Three 版本里有变化老版本是简单的倍数新版本引入了物理光照单位同样的1.0在两个版本下亮度能差一倍。如果你发现模型在开发者工具里正常、真机上过曝或者发灰先查版本别急着调参数——这是我见过最多人浪费时间的地方。3.3 渲染循环替掉 window.requestAnimationFrame浏览器里用window.requestAnimationFrame小程序里没有这个全局方法但 canvas 节点自带了同名方法。注意是节点上的方法不是wx.开头的 APIstartLoop() { const loop () { // 用 canvas 的方法续帧返回值用于后续取消 this.rafId this.canvas.requestAnimationFrame(loop) // 简易节流不追求 60 帧30 帧对展示类场景足够 const now Date.now() if (now - (this.lastFrameTime || 0) 33) return this.lastFrameTime now if (this.model this.autoRotate) { this.model.rotation.y 0.008 } this.renderer.render(this.scene, this.camera) } loop() }, stopLoop() { if (this.rafId this.canvas) { this.canvas.cancelAnimationFrame(this.rafId) this.rafId null } }节流那段不是可有可无的优化。中低端安卓机上一个中等面数的 glb 模型跑满 60 帧GPU 占用会飙到很高手机会明显发热用户切后台再回来就发现页面卡成 PPT。压到 30 帧肉眼几乎看不出差别功耗能降将近一半。33这个数是 1000/30 取整想要 24 帧就改成 41。更关键的是必须能停下来。页面隐藏、跳转、卸载时不停循环requestAnimationFrame 会一直排队渲染器持续往一块已经不可见的画布上绘制内存和 GPU 资源都不释放。反复进出同一个页面五六次内存就能翻倍。onHide() { this.stopLoop() }, onUnload() { this.stopLoop() this.disposeAll() }, onShow() { // 回到前台重新起循环注意别重复 start 造成多路循环 if (!this.rafId this.renderer) { this.startLoop() } }onShow里那个if (!this.rafId)判断很有必要。如果onHide因为某种原因没触发比如页面被系统回收再startLoop就会同时跑两条循环帧率翻倍功耗翻倍模型转速也翻倍看起来像「转得特别快」的玄学 bug。4. 外部模型加载GLTFLoader 解析链路的改造4.1 load(url) 走不通的原因拿到GLTFLoader之后本能反应是照着文档写loader.load(url, onLoad)。这段代码在小程序里跑起来不会报错回调也永远不会触发控制台一片安静。原因在FileLoader内部。它做三件事创建XMLHttpRequest、监听progress事件、把响应按arraybuffer或text取出来。小程序没有XMLHttpRequest适配层一般会塞一个极简 shim 进去让它别崩但这个 shim 只保证不抛异常不保证真的发请求。于是 loader 一直等一个永远不来的响应。glb是二进制格式.gltf是 JSON两者最终都归一成parse(arrayBuffer | json, path, onLoad, onError)。既然网络请求这层小程序有能力自己做那就把请求和解析拆开wx.request负责拉数据loader.parse负责解析。这是所有小程序 3D 项目绕不开的一步。4.2 wx.request 拉二进制 loader.parseloadModel() { const THREE this.THREE const url https://cdn.example.com/models/robot.glb wx.showLoading({ title: 模型加载中, mask: true }) wx.request({ url, method: GET, responseType: arraybuffer, // 必须是这个默认是 text 会直接损坏二进制 timeout: 20000, success: (res) { if (res.statusCode ! 200) { wx.hideLoading() wx.showToast({ title: HTTP ${res.statusCode}, icon: none }) return } this.parseModel(res.data) }, fail: (err) { wx.hideLoading() console.error(模型下载失败, err) wx.showToast({ title: 下载失败, icon: none }) } }) }, parseModel(buffer) { const THREE this.THREE // 工厂函数式引入把 scoped THREE 注入进去 const GLTFLoader require(../../libs/GLTFLoader.js)(THREE) const loader new GLTFLoader() // 第二个参数是资源根路径glb 内部自带贴图时可以传空字符串 loader.parse(buffer, , (gltf) { wx.hideLoading() const model gltf.scene this.fitCamera(model) this.scene.add(model) this.model model }, (err) { wx.hideLoading() console.error(模型解析失败, err) wx.showToast({ title: 解析失败, icon: none }) }) }responseType: arraybuffer是这段代码里唯一的硬性参数写错成默认值text拿到的是一个被 UTF-8 解码破坏过的字符串loader.parse会在读取文件头 magic number 的时候直接抛异常报错信息大概是「Unsupported glTF-Binary header」看起来像是模型文件坏了其实是请求参数的问题。loader.parse的第二个参数path决定相对路径资源的解析基准。纯glb贴图、几何全内嵌传空串就行如果是.gltf.bin 一堆.png的分离结构这里要传模型所在目录的完整 URL末尾带斜杠。传错的后果是贴图静默丢失模型变成灰色——不报错只是加载器把纹理请求发出去了但取不回来。注意wx.request要求域名在白名单里。开发阶段可以在开发者工具里勾「不校验合法域名」真机预览时必须配好业务域名否则请求直接 fail且错误码被合并成笼统的request:fail看不出具体原因。4.3 贴图加载canvas.createImage 替代 new Imageglb内嵌贴图的话上面那段代码就能跑出完整效果。一旦碰到外链贴图就得自己接管图片加载。TextureLoader内部走的是new Image()小程序里没有这个构造函数替代品是canvas.createImage()// 通用纹理加载先拿到可用的本地路径再喂给图片对象 function loadTexture(canvas, THREE, remoteUrl) { return new Promise((resolve, reject) { // 网络图片先走 getImageInfo 拿临时路径否则 img.src 直接赋 URL 可能失败 wx.getImageInfo({ src: remoteUrl, success: (info) { const img canvas.createImage() img.onload () { const texture new THREE.Texture(img) texture.needsUpdate true // 手动构造的纹理必须显式标记 resolve(texture) } img.onerror () reject(new Error(图片解码失败: remoteUrl)) img.src info.path }, fail: reject }) }) }用的时候是在模型加载完成之后遍历材质把map换掉loadExternalTextures(model, textureUrl) { loadTexture(this.canvas, this.THREE, textureUrl).then((texture) { model.traverse((child) { if (!child.isMesh || !child.material) return const mats Array.isArray(child.material) ? child.material : [child.material] mats.forEach((mat) { if (mat.map) mat.map.dispose() // 先释放旧的避免显存叠加 mat.map texture mat.needsUpdate true // 材质参数变了必须重新编译 }) }) }).catch((err) console.error(贴图替换失败, err)) }texture.needsUpdate true和mat.needsUpdate true这两个标记缺一不可。前者告诉渲染器这张纹理还没上传过 GPU后者告诉渲染器着色器需要重新编译。少任何一个的表现都是「模型有颜色但贴图不显示」而且不报任何错属于典型的黑匣子问题。颜色空间还有个小坑模型的贴图通常是 sRGB渲染器的输出也要设成对应的编码否则整体会偏暗或者发灰。老版本里是renderer.outputEncoding THREE.sRGBEncoding新版本换成了renderer.outputColorSpace THREE.SRGBColorSpace具体用哪个看你手上这版 THREE 暴露了什么。4.4 包围盒自适应模型大小不一也不用手动调相机从外面拿到的模型单位可能是米、厘米、毫米原点可能在几何中心也可能在脚底。写死camera.position.set(0, 0, 5)的结果是有的模型糊在脸上有的模型只剩一个小点。正确做法是加载完成后算包围盒按尺寸反推相机距离顺便把模型挪到原点这样旋转手势才是绕自身中心转fitCamera(object) { const THREE this.THREE const box new THREE.Box3().setFromObject(object) const size box.getSize(new THREE.Vector3()) const center box.getCenter(new THREE.Vector3()) // 平移模型让它围绕原点旋转 object.position.sub(center) object.position.y size.y / 2 // 需要落地感时把底面对齐到 y0 const maxSize Math.max(size.x, size.y, size.z) const fovRad (this.camera.fov * Math.PI) / 180 // 由视场角和模型最大边长反推最小可视距离 const distance (maxSize / 2) / Math.tan(fovRad / 2) this.camera.position.set(0, size.y * 0.3, distance * 1.4) this.camera.near distance / 100 this.camera.far distance * 100 this.camera.lookAt(0, 0, 0) this.camera.updateProjectionMatrix() // 改了 near/far 必须手动更新投影矩阵 // 记录初始距离供手势缩放时做上下限约束 this.baseDistance distance * 1.4 }1.4这个系数是留白让模型四周有点呼吸空间压到1.1会显得很挤放到2.0又太小。camera.position.y用size.y * 0.3是个折中纯俯视太平纯平视又看不到顶面结构。updateProjectionMatrix()那行漏掉的概率极高。near和far是相机投影矩阵的组成部分改了属性不调用这个方法渲染器还用旧矩阵表现是近处被裁掉一块或者远处消失而且不管你怎么调参数都没反应。5. 踩坑排查真机黑屏、贴图丢失和内存不回收5.1 开发者工具正常真机白屏现象工具里模型转得好好的扫码真机预览一片白控制台没有任何 WebGL 相关报错。原因九成是画布尺寸问题。前面提到canvas.width和setSize都乘了 dpr实际缓冲区被放到四倍大超出部分直接空白另一种情况是SelectorQuery没加.in(this)取到的是上一个页面残留的节点。解决先把canvas.width/canvas.height/renderer.getSize()三个值打到日志里对一遍正常情况下前两个相等第三个是它们的值。再确认setPixelRatio(1)。真机调试时打开「vConsole」看实时日志比在开发者工具里猜快得多。5.2 模型上屏但是全黑或者只剩剪影现象加载成功、scene.children里能看到模型画面却完全没有材质细节。原因材质是MeshStandardMaterial或MeshPhysicalMaterial这两种材质完全依赖光源没有光照就是纯黑。另外模型自带的KHR_materials_*扩展在旧版加载器里不被识别会被降级成默认灰色材质。解决先补一盏AmbientLight打底强度给到0.6以上再检查控制台有没有「Unknown extension」之类的警告有的话要么升级加载器要么在loader.parse之后遍历材质手动设MeshBasicMaterial兜底。展示类场景用基础材质反而更可控不必强求物理材质。5.3 贴图丢失模型整体发灰现象几何形状完全正确但表面是单一灰色没有任何图案。原因分离式 glTF 的贴图路径解析失败。loader.parse的path参数传了空串或者传了页面相对路径加载器拼出来的图片地址是错的请求失败后被静默吞掉。另一种可能是blob:协议的 URL 在小程序里根本不可用。解决优先让美术导出一个内嵌贴图的.glb文件大一点但省掉整条路径解析链路。实在要用外链就按 4.3 的做法自己接管纹理加载加载完成后按材质名精确替换别指望加载器自动搞定。5.4 页面来回进出几次就卡死现象第一次进页面流畅进出三五次之后明显卡顿最终白屏或者小程序直接闪退。原因requestAnimationFrame没有取消渲染循环在后台一直跑同时几何体、材质、纹理的 GPU 资源没有dispose每进一次页面就泄漏一份。解决onHide停循环onUnload停循环并执行完整清理。清理要递归遍历disposeAll() { if (this.model) { this.model.traverse((child) { if (child.geometry) child.geometry.dispose() if (!child.material) return const mats Array.isArray(child.material) ? child.material : [child.material] mats.forEach((mat) { // 材质上的每一张纹理都要单独释放 Object.keys(mat).forEach((key) { const val mat[key] if (val val.isTexture) val.dispose() }) mat.dispose() }) }) this.scene.remove(this.model) this.model null } if (this.renderer) { this.renderer.dispose() this.renderer null } }isTexture判断比写死mat.map.dispose()稳因为一个材质可能同时挂了map、normalMap、roughnessMap好几张纹理只释放主贴图等于没清理。5.5 手势旋转一顿一顿的现象手指滑动时模型转动不跟手有延迟感。原因touchmove里直接改了rotation但渲染循环是 30 帧节流事件频率远高于渲染频率中间大量计算被丢弃或者touchmove触发了setData页面逻辑层和渲染层通信开销把主线程堵住了。解决touchmove里只更新旋转缓存值真正的赋值放在渲染循环里做整个交互链路里一次setData都不要调。3D 场景的所有状态都放this上data只用于驱动 WXML 里那几个无关紧要的文案。6. 二次开发从能看会转到性能兜底的改造清单模型能转起来只是起点真正交付前还得过几关。下面这几条是我在这个工程上反复改过的地方按优先级排改造方向具体改动需要留意的地方手势交互单指旋转 双指捏合缩放缩放要基于baseDistance做上下限别让用户把相机推进模型内部自动旋转无操作 2 秒后恢复自转用定时器记录最后交互时间touchstart里重置性能兜底低端机降帧、降 pixelRatiowx.getDeviceInfo拿机型档位中低端直接把 dpr 压到 1.5模型预加载上一个页面空闲时提前wx.request把 arraybuffer 缓存到全局进页面直接parse省掉等待多模型切换保留 renderer只换 model切换时先dispose旧的再加载新的避免显存翻倍双指缩放的实现比旋转麻烦一点核心是记录两个触点的距离变化onTouchMove(e) { if (!this.model) return if (e.touches.length 2) { // 双指算两点间距和上一次比得出缩放系数 const dx e.touches[0].clientX - e.touches[1].clientX const dy e.touches[0].clientY - e.touches[1].clientY const dist Math.sqrt(dx * dx dy * dy) if (this.lastPinch) { const scale dist / this.lastPinch const next this.camera.position.z / scale // 约束在基准距离的 0.5 到 2 倍之间 const min this.baseDistance * 0.5 const max this.baseDistance * 2 this.camera.position.z Math.min(max, Math.max(min, next)) this.camera.lookAt(0, 0, 0) } this.lastPinch dist this.lastTouchTime Date.now() return } // 单指只更新缓存渲染循环里统一应用 const t e.touches[0] if (this.lastX ! null) { this.pendingRotY (this.pendingRotY || 0) (t.clientX - this.lastX) * 0.01 this.pendingRotX (this.pendingRotX || 0) (t.clientY - this.lastY) * 0.01 } this.lastX t.clientX this.lastY t.clientY this.lastTouchTime Date.now() }pendingRotX和pendingRotY这两块缓存是「跟手」的关键渲染循环里再一次性累加到model.rotation上。如果直接在事件回调里改rotation30 帧节流会让手指的位移被丢掉大半手感就变成了「划半天转一点」。切换模型那段也有个容易忽略的点新的模型加载完成之前旧的不能删。常见做法是先把新模型的arraybuffer请求发出去success回调里再执行「移除旧的 → 解析新的 → 加到场景」这样界面中间会有一小段空白但不会闪。如果反过来先删后加载网络慢的时候用户看到的就是纯背景色体感很差。关于低端机降级我的做法是在初始化阶段读一次设备信息const info wx.getDeviceInfo() // benchmarkLevel 是微信给的整机性能参考值越低越吃力 const isLowEnd info.benchmarkLevel ! null info.benchmarkLevel 10 const dpr isLowEnd ? 1 : (wx.getSystemInfoSync().pixelRatio || 2)benchmarkLevel这个值不是所有机型都有拿不到时按中端处理。低端机上把 dpr 压到 1画面会糊一点但好歹能转起来高分辨率配卡顿的体验比低分辨率流畅要差得多。最后说个习惯。这个项目之后我每次做小程序 3D都会先写一个最小验证页一块 canvas、一个立方体、一盏灯、一个循环别的什么都不加。这段代码能在这个机型上跑出画面才说明适配层、尺寸计算、渲染循环这三层是通的再往上堆模型和交互。跳过这一步直接上真实模型出问题时你分不清是环境没搭好还是模型有问题排查成本翻好几倍。希望帮到你。本文还有配套的精品资源点击获取
