小程序 three.js 3D模型加载渲染与性能优化实践

简介面向微信小程序开发者的 three.js 外部 3D 模型加载示例工程适合具备 JavaScript 与小程序基础、需要在项目中接入模型并完成场景渲染的开发者参考。压缩包共 11 个文件、约 167KB含 4 个 json 配置、4 个 js 逻辑脚本、1 个 md 说明、1 个 wxss 样式和 1 个 wxml 页面文件覆盖页面结构、脚本模块与项目配置便于对照目录关系理解工程组织。已有 3208 人学习下载说明移动端 3D 展示方向具有稳定关注度。工程围绕模型加载、场景初始化、渲染循环与触摸交互组织代码涉及模型格式处理、动画生命周期和性能优化等常见难点可作为商品展示、虚拟展厅或教育演示类小程序的起步模板说明文档有助于快速定位入口文件、梳理模块职责并在此基础上替换模型、调整渲染参数降低从零搭建 3D 页面的试错成本。整体结构精简适合作为二次开发底稿。1. 一个模型转不起来的下午这套 demo 到底解决了什么需求很具体客户要在小程序里让用户手指转着看产品模型不能跳 H5也不能装 App。团队第一反应是把 Web 端那套 three.js 代码搬过来结果 import 完直接报document is not defined改完又是白屏模型死活不出现。这个小程序项目就是专门解决这件事的工程骨架——它把 three.js 的运行时补丁、canvas 节点绑定、外部 glTF/GLB 模型加载、渲染循环、单指旋转双指缩放、以及退出页面时的资源释放串成了一条能跑的链路。JavaScript 全程没有原生插件没有云端渲染。适合已经会点 JS、想在小程序里做 3D 展示或 AR 前置预览的开发者不适合想直接拿到 AR 识别能力的人那得换另一套东西。下面按我拆包的顺序讲先看它跨了哪几道坎再看模型怎么进来最后看怎么改成你自己的组件。2. 架构拆解three.js 在小程序里要跨过哪三道坎2.1 渲染层差异为什么不能把 Web 版 three.js 直接 import 进来Web 上的 three.js 是建立在浏览器 DOM 之上的。它内部会调用document.createElementNS(canvas)创建离屏画布来做纹理和 RenderTarget会读window.devicePixelRatio会用XMLHttpRequest拉资源用requestAnimationFrame驱动循环用Image和URL.createObjectURL处理贴图。小程序环境里这些对象一个都没有没有document没有windowcanvas 是一个原生组件必须先用createSelectorQuery().select(#id).node()才能拿到真实的 Canvas 对象动画帧要靠canvas.requestAnimationFrame。所以适配层的本质非常朴素给 three.js 补一个最小可用的 DOM 壳子。社区里流传的three.weapp.js或者createScopedThreejs就是这个思路——把 three 的源码包进闭包导出一份带补丁的 THREE 命名空间。常见的补丁点有这么几个缺失能力补丁方式不补的后果document.createElementNS返回wx.createOffscreenCanvas生成纹理时直接抛错requestAnimationFrame转发到canvas.requestAnimationFrame渲染循环不跑只有黑屏XMLHttpRequest用wx.request/wx.downloadFile模拟Loader 卡在 pendingdevicePixelRatio读wx.getSystemInfoSync().pixelRatio高分屏糊成一片Image用canvas.createImage()贴图加载不进来这里踩过一次坑很多人以为适配层是什么高深黑科技其实它就是在替 three 骗过环境检测。你只要记住一句话——凡是 three 里跟「浏览器」三个字沾边的调用都得在适配层找到对应物找不到就会在真机上以各种奇怪姿势翻车。2.2 目录结构一个能跑的最小工程长什么样拆这类 demo 我习惯先看目录因为目录基本等于作者的思考边界。这个工程的层次划分很干净页面层只管生命周期和事件libs 层是「不可改的第三方 适配」utils 层放可复用的加载与场景封装路径职责改不改pages/index/入口页模型列表 / 参数选择随便改pages/viewer/3D 查看页持有一个 canvas 和一个渲染器主要改这里libs/three.weapp.js打过补丁的 three 运行时CommonJS尽量别动升级时整体替换libs/GLTFLoader.jsglTF/GLB 解析器必须在适配层之后引入别动libs/three.adapter.jscanvas → THREE 的桥接入口谨慎改改错全崩utils/modelLoader.js远程模型下载 解析 缓存常改接 CDN 就靠它utils/scene.js相机、光照、地面、控制器初始化常改app.json页面注册、renderer: webgl相关配置按需有个细节值得说libs里的 three 是打包过的单文件不是node_modules里那份。因为小程序 npm 构建只做模块解析和转译不会替你处理「运行时缺失 DOM」的问题直接把 npm 版 three import 进来编译能过跑起来必挂。2.3 初始化三步拿节点、造 THREE、建渲染器真正把 three 拉起来的代码不超过二十行但每一行的参数都有讲究。下面是页面的onReady主干// pages/viewer/viewer.js import { createScopedThreejs } from ../../libs/three.adapter Page({ data: { ready: false, modelUrl: }, onReady() { // 第一步小程序没有 document.getElementById只能走选择器 node() wx.createSelectorQuery() .select(#webgl) .node() // 关键不加 .node() 拿到的是描述对象不是 Canvas .exec((res) { const canvas res[0].node // 小程序 canvas 默认 300x150必须手动设成物理像素尺寸 const info wx.getSystemInfoSync() const dpr Math.min(info.pixelRatio || 1, 2) // 老机型别硬顶 3会掉帧 canvas.width res[0].width * dpr canvas.height res[0].height * dpr // 第二步用真实 canvas 生成带补丁的 THREE const THREE createScopedThreejs(canvas) // 第三步渲染器必须显式接收 canvas它会跳过内部 createElement 逻辑 const renderer new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false, powerPreference: high-performance }) renderer.setPixelRatio(dpr) renderer.setSize(canvas.width, canvas.height, false) // false别再改 style renderer.outputColorSpace THREE.SRGBColorSpace // 新版写法老版是 outputEncoding renderer.toneMapping THREE.ACESFilmicToneMapping renderer.toneMappingExposure 1.0 this.ctx { canvas, THREE, renderer } this.setData({ ready: true }) }) }) })几个参数值得逐条解释。setPixelRatio和setSize里的canvas.width / canvas.height用的都是物理像素第三个参数传false是为了让 three 不要去写canvas.style——小程序 canvas 节点压根没有style这个可写属性传true会静默失败或者报错。outputColorSpace这一行是分水岭three r152 之后改成了outputColorSpace之前的版本叫outputEncoding写错不报错只是模型颜色发灰或者过曝属于典型的「看着像灯光问题其实是色彩空间问题」。antialias在低端安卓机上建议关掉锯齿换帧率用户其实感知不到。对应的 wxml 只要一句!-- pages/viewer/viewer.wxml -- canvas typewebgl idwebgl stylewidth: 100%; height: 100%; bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd /typewebgl不能省写成2d拿到的上下文根本创建不了 WebGLRenderer。canvas 用style控制显示尺寸CSS 像素用 JS 控制width/height属性物理像素这两套尺寸不一致时触摸坐标换算就会错位第五章还会再提一次。2.4 依赖引入的两条路npm 构建还是本地打包工程里其实有两种引入姿态选错了会浪费半天。第一种是走小程序 npmnpm i three然后开发者工具里「构建 npm」生成miniprogram_npm。这条路的问题在于构建出来的 three 依旧是「浏览器版」WebGLRenderer内部还是会去找document除非你把适配补丁包在它外层。第二种是本地用 rollup/webpack 把threeadapter打成一个 CommonJS 单文件放进libs/工程里到处require。这个 demo 走的是第二条。我一般的做法是项目根目录建一个build/放打包脚本package.json里锁死 three 的版本three: 0.15x.x精确版本不用^每次升级就在本地跑一次打包产物拷进libs同时把版本号写进libs/VERSION.md。这么干的好处是升级路径可回滚——适配层和 three 的版本是强耦合的r150 之前和之后的 API 差异能让你改到怀疑人生留个后悔药总没错。3. 加载主链路从一条远程 URL 到屏幕上的第一帧3.1 GLTFLoader 在小程序里的两个改造点three 自带的GLTFLoader内部依赖FileLoader而FileLoader底层是XMLHttpRequest。如果适配层已经把 XHR 桥接到了wx.request那loader.load(url, ...)理论上能跑但实际项目里我更推荐绕开这条路自己用wx.downloadFile下载到本地临时文件再用loader.parse解析二进制。原因有三能显示真实下载进度、能命中本地缓存、能精确控制合法域名报错的提示。// utils/modelLoader.js const cache new Map() // key: url, value: THREE.Group export function loadModel(THREE, url, onProgress) { if (cache.has(url)) return Promise.resolve(cache.get(url)) return new Promise((resolve, reject) { const task wx.downloadFile({ url, // 必须是后台配置过的 downloadFile 合法域名 success(res) { if (res.statusCode ! 200) { return reject(new Error(模型下载失败 HTTP ${res.statusCode})) } // 读成 ArrayBufferGLB 是二进制用 utf8 读会直接乱码 wx.getFileSystemManager().readFile({ filePath: res.tempFilePath, success({ data }) { const loader new THREE.GLTFLoader() // 第二个参数是资源根路径解析 .gltf 里的相对贴图时才会用到 loader.parse(data, , (gltf) { cache.set(url, gltf.scene) resolve(gltf.scene) }, reject) }, fail: reject }) }, fail: reject }) // downloadFile 返回的 task 支持进度回调用来做加载条 if (onProgress) { task.onProgressUpdate(({ progress }) onProgress(progress)) } }) }参数说明url必须走wx.downloadFile的合法域名校验本地调试时记得在开发者工具里勾「不校验合法域名」否则真机上一定 403而开发者工具里一切正常——这个差异坑过太多人。loader.parse第二个参数path传空字符串时.gltf里写的相对贴图路径会解析失败所以线上优先用.glb单文件格式把所有几何、材质、贴图打进一个二进制包里从根上避免相对路径问题。cache这一层也别省。用户从列表点进详情、返回、再点另一件如果每次都重新下载解析等待时间会翻倍而且 WebGL 纹理内存会一直涨。3.2 场景搭建相机、光照、色调映射模型进来之后能不能看八成取决于光和相机而不是模型本身。下面这段是utils/scene.js的核心// utils/scene.js export function createScene(THREE, canvas) { const scene new THREE.Scene() scene.background new THREE.Color(0x101418) // FOV 45~55 之间最接近人眼near/far 别拉太大否则深度精度不够会闪面 const camera new THREE.PerspectiveCamera( 45, canvas.width / canvas.height, 0.1, 100 ) camera.position.set(0, 1.2, 3.2) camera.lookAt(0, 0.6, 0) // 小程序端不要迷信 IBL / HDR 环境贴图PMREM 生成慢且吃内存 const ambient new THREE.AmbientLight(0xffffff, 0.8) const key new THREE.DirectionalLight(0xffffff, 1.6) key.position.set(3, 5, 4) const fill new THREE.DirectionalLight(0xffffff, 0.5) fill.position.set(-4, 3, -2) scene.add(ambient, key, fill) return { scene, camera } }AmbientLight的强度在整个场景中起基础照明作用DirectionalLight负责塑形。很多人第一次加载模型发现「全黑」第一反应是模型坏了实际就是忘了加灯——MeshStandardMaterial在没有光源的环境下就是纯黑。AmbientLight强度给到 0.8 只是兜底真正让模型有立体感的是主光的角度(3, 5, 4)这种右上前方的位置基本能覆盖大多数产品模型。camera.lookAt的目标点建议按模型包围盒中心动态算硬编码(0, 0.6, 0)只对特定模型成立。3.3 渲染循环与首帧别用 window.requestAnimationFrame渲染循环看着简单但小程序里有两个限制一是全局没有requestAnimationFrame必须用canvas.requestAnimationFrame二是页面切后台时部分基础库会把 canvas 的渲染暂停你得自己处理断电和恢复。// pages/viewer/viewer.js承接初始化 startLoop() { const { canvas, renderer } this.ctx const clock new this.ctx.THREE.Clock() const render () { this.rafId canvas.requestAnimationFrame(render) const dt clock.getDelta() if (this.model this.autoRotate !this.dragging) { this.model.rotation.y dt * 0.4 // 0.4 弧度/秒慢一点更像展示 } renderer.render(this.scene, this.camera) } render() }, onHide() { // 页面不可见时必须停否则后台持续跑 GPU回前台容易上下文丢失 if (this.rafId) { this.ctx.canvas.cancelAnimationFrame(this.rafId) this.rafId null } }, onShow() { if (!this.rafId this.ctx) this.startLoop() }clock.getDelta()而不是固定步长是为了让动画速度跟帧率解耦——低端机 30fps、高端机 60fps用固定步长会让转动速度差一倍。onHide里停循环这一步属于血泪经验早期不做的时候用户在详情页反复进出三次第四次一定是黑屏。3.4 触摸交互把 touch 映射成球坐标交互这块最容易出错的不是数学是坐标系。渲染循环里管理相机用的是球坐标theta、phi、radius触摸事件只负责给增量// pages/viewer/viewer.js onTouchStart(e) { this.dragging true this.lastX e.touches[0].x // canvas 上绑定的事件坐标相对 canvas this.lastY e.touches[0].y if (e.touches.length 2) { this.lastDist this.getDistance(e.touches) } }, onTouchMove(e) { const { camera } this if (e.touches.length 1 this.lastX ! null) { const dx e.touches[0].x - this.lastX const dy e.touches[0].y - this.lastY this.theta - dx * 0.01 // 系数控制灵敏度 this.phi Math.max(0.2, Math.min(Math.PI - 0.2, this.phi - dy * 0.01)) this.lastX e.touches[0].x this.lastY e.touches[0].y this.updateCamera() } else if (e.touches.length 2) { const dist this.getDistance(e.touches) this.radius Math.max(1.5, Math.min(8, this.radius * (this.lastDist / dist))) this.lastDist dist this.updateCamera() } }, updateCamera() { const { camera } this // 球坐标转笛卡尔这里是把相机绕着原点转不是把模型转 camera.position.x this.radius * Math.sin(this.phi) * Math.sin(this.theta) camera.position.y this.radius * Math.cos(this.phi) camera.position.z this.radius * Math.sin(this.phi) * Math.cos(this.theta) camera.lookAt(this.center) }phi夹在0.2 ~ π-0.2之间是为了防止相机翻到正上方或正下方导致lookAt出现万向锁抖动。灵敏度系数0.01是按 375pt 宽屏幕调的换到平板上会显得太慢建议按canvas 宽度 / 375做一次归一化。radius限制在1.5 ~ 8是给双指缩放留的余量太小会穿进模型内部太大模型只剩一个小点。4. 性能与体验包体、纹理和首屏三秒4.1 模型体积GLB 优先减面优先于压缩小程序主包体积有硬上限常见是 2MB 左右整包 20MB把模型打进包里是最差的选择。这个 demo 的模型全部走远程 URL包里只有代码。模型侧我的优先级排序是先减面再压纹理最后才考虑几何压缩。Draco 听着很美但在小程序里要用 wasm 解码器而 wasm 的加载和内存限制在低端机上很不稳定属于「能跑但不敢上线」的范畴。相比之下meshopt或者干脆在建模软件里把面数从 20 万降到 3 万效果更直接。纹理方面2048×2048 的 PNG 单张解码后占内存2048×2048×4 ≈ 16MB三张就能把中低端安卓机的 WebGL 上下文顶掉降到 1024 并且转成 JPG体积和内存都是四分之一起。优化项操作典型收益格式glTF bin 贴图 → GLB 单文件请求数 3~5 → 1面数建模软件里减面 / 加 LOD顶点数降 60%~80%纹理2048 PNG → 1024 JPG内存降 75%包体降 80%材质多材质 → 合并 一张图集draw call 大幅下降压缩Draco谨慎/ meshopt体积降 50%解码有成本4.2 运行时内存dispose 不是可选项小程序页面每次navigateTo都会新建一个 WebGL 上下文而系统对同时存在的上下文数量是有限制的。如果退出页面时不dispose第三次进入基本就是黑屏或者直接闪退。// pages/viewer/viewer.js onUnload() { const { renderer, canvas } this.ctx || {} if (!renderer) return // 1. 停循环 if (this.rafId) canvas.cancelAnimationFrame(this.rafId) // 2. 逐个释放几何体和材质遍历整棵场景树 this.scene.traverse((obj) { if (obj.geometry) obj.geometry.dispose() if (obj.material) { const mats Array.isArray(obj.material) ? obj.material : [obj.material] mats.forEach((m) { Object.values(m).forEach((v) { if (v v.isTexture) v.dispose() }) m.dispose() }) } }) // 3. 最后才是 renderer顺序反了会报 context lost renderer.dispose() renderer.forceContextLoss() this.ctx null }顺序很重要先停循环再释放几何体和材质最后renderer.dispose()加forceContextLoss()。少了forceContextLoss某些机型上上下文不会真正归还你会在第三次进入时看到控制台刷Too many active WebGL contexts。4.3 加载态与降级别让用户盯着黑屏三秒是个心理阈值。超过三秒没有任何反馈用户就会以为卡死。这个 demo 的做法是三层兜底下载阶段用onProgressUpdate驱动一个环形进度解析阶段切到「正在准备模型」文案渲染首帧后再淡入。降级则是在onError里判断 WebGL 是否可用不可用就直接展示一张静态图加「点击查看大图」。// 首帧渲染完成后再隐藏 loading避免闪白 renderer.render(scene, camera) wx.nextTick(() this.setData({ loading: false }))wx.nextTick这一句是为了让 setData 排在首帧绘制之后直接同步调用的话某些机型上 loading 消失和画面出现之间会有一帧白。5. 避坑与排查五个让我加班到凌晨的现场问题5.1 开发者工具一切正常真机白屏现象模拟器里模型转得好好的扫码到真机canvas 区域一片空白控制台没有任何报错。原因绝大多数是 canvas 尺寸问题。wxml 里只写了stylewidth:100%;height:100%父容器高度是 0比如 flex 布局没给高度select().node()拿到的res[0].width/height就是 0renderer.setSize(0, 0)之后什么都不画。模拟器对 0 尺寸比较宽容真机直接摆烂。解决给父容器写死高度height: 100vh并在初始化前打印一次res[0].width做断言为 0 就 abort 并提示。我一般还会在setSize之后加一句console.log(canvas.width, canvas.height)跑通一次就删。5.2 模型是黑的或者白到过曝现象模型加载出来了轮廓也对但整体发黑或者白得像曝了光调光强也没用。原因大概率是色彩空间没设对。three 在 r152 之后把outputEncoding改成了outputColorSpace贴图侧也从texture.encoding改成texture.colorSpace。老代码跑在新版本上不报错只是颜色全程错位。另一个常见原因是模型用了MeshStandardMaterial但场景里只有一个AmbientLight没有方向光金属度一高就是纯黑。解决渲染器设outputColorSpace THREE.SRGBColorSpace颜色贴图设texture.colorSpace THREE.SRGBColorSpace非颜色贴图比如法线、粗糙度不要设。再补一盏方向光。判断顺序是先看有没有光再看色彩空间最后才怀疑模型。5.3 贴图全丢只剩纯色现象几何体在颜色是材质的基础色但花纹、logo、法线细节全没了控制台偶尔有一条资源 404。原因.gltf是分离格式贴图靠相对路径引用loader.parse(data, , ...)第二个参数传空相对路径解析不到或者贴图在另一个域名上downloadFile合法域名没配请求直接失败。解决线上统一用.glb把所有资源打进一个二进制包。如果是设计给的.gltf用工具转成.glb再上传别在运行时拼路径。另外把贴图域名和模型域名统一成一个。5.4 第二次进入页面黑屏内存一路涨现象首次进详情页正常返回再进画面黑掉反复几次后小程序直接闪退。原因WebGL 上下文没释放。onUnload里什么都没做几何体、材质、纹理、renderer 全留在显存里系统对活跃上下文数量有限制超了就把最早的那个强行回收。解决按 4.2 的顺序完整 dispose特别是renderer.forceContextLoss()。另外把模型缓存从「无限增长」改成 LRU最多留两个。5.5 手指滑动模型不转或者方向反了现象单指拖动没反应或者往右拖模型往上跑双指缩放时模型瞬移。原因坐标系搞混了。在 canvas 上绑bindtouchstart事件对象里touches[0]的x/y是相对 canvas 的但如果绑在页面外层容器上拿到的是clientX/clientY相对视口两者差了一个 canvas 的偏移量。另外如果 canvas 的物理像素和 CSS 像素不一致dx会被放大 dpr 倍看起来就是「动一下就飞了」。解决事件一律绑在 canvas 上用x/y而不是clientX/clientY。灵敏度系数除以 dpr。缩放判断先比touches.length 2再算两指距离同时要在touchend里把lastDist清掉否则下一轮双指会用到上一轮的残留值导致模型瞬移。6. 二次开发把它改成你自己的 3D 组件这个 demo 本身是个页面直接当组件用会很别扭。我在实际项目里的做法是把它抽成自定义组件对外只暴露model一个必填属性其余全给默认值。改造的核心是三件事把 canvas 的选取从页面级挪到组件级用this.createSelectorQuery()、把渲染器实例挂在组件实例上而不是 Page 上、把加载和销毁绑到组件的lifetimes。// components/model-viewer/index.js Component({ properties: { model: { type: String, value: , observer: onModelChange }, autoRotate: { type: Boolean, value: true }, scale: { type: Number, value: 1 }, background: { type: String, value: #101418 } }, lifetimes: { ready() { // 组件内必须用 this.createSelectorQuery()用 wx. 那个查不到自己 this.createSelectorQuery() .select(#webgl).node() .exec((res) { res[0] this.init(res[0].node, res[0].width, res[0].height) }) }, detached() { this.destroy() } // 关键组件销毁必须走完整 dispose }, methods: { onModelChange(url) { if (!this.ctx || !url) return loadModel(this.ctx.THREE, url, (p) this.triggerEvent(progress, { progress: p })) .then((root) this.applyModel(root)) .catch((err) this.triggerEvent(error, { message: err.message })) } } })对外属性我建议收敛到五个以内多一个就多一份兼容负担属性类型默认值说明modelString空GLB 远程地址必填autoRotateBooleantrue是否自动缓慢旋转scaleNumber1模型整体缩放用于统一不同来源的模型backgroundString#101418场景底色跟页面风格对齐bindloadEvent-首帧渲染完成时触发有一个技巧值得单独说多模型切换时不要重建渲染器。渲染器重建的代价在低端机上接近一秒用户会看到明显白闪。正确姿势是保留 renderer 和 scene只把旧模型的根节点remove掉并 dispose再把新模型add进来相机位置根据新模型的包围盒重新计算一次radius。这样切换基本是无感的。验证方法也很固定准备三个标准测试模型——一个带透明材质、一个带法线贴图、一个顶点数超过十万。每次改完适配层或者升级 three 版本三个模型依次过一遍能同时跑通基本就没大问题。我吃过一次亏只拿一个简单模型验证上线后用户上传的带透明贴图的模型整个糊成一片原因是transparent材质的渲染顺序在补丁版里跟官方版有差异。从那以后我每次动libs目录下的任何文件都强制走一遍「三个模型 真机 连续进出五次」的回归一步不省。这套流程看着笨但省下来的返工时间远比它多。希望帮到你。本文还有配套的精品资源点击获取