微信小程序接入 Three.js 渲染 glb 3D 模型实战

简介这份源码包面向微信小程序开发者与前端初学者聚焦在小程序环境中整合three.js并展示3D模型的实战需求适合刚接触小程序三维能力、希望用最小示例打通流程的读者帮助绕开库引入、模型加载与渲染适配中的常见问题。包内共18个文件以8个js脚本、5个json配置、2个wxml页面、2个wxss样式和1个gltf模型为主分别承担业务逻辑、项目配置、页面结构、视觉样式与三维模型资源压缩包约258KB体量轻便、结构清晰页面与组件分层组织便于按需阅读和二次修改。已有2309人学习可作为入门示例参考。读者能直接运行基础演示快速理解three.js在小程序中的接入方式并基于脚本中的函数调整旋转、掉落等动画效果附带的虾模型上传服务器后可在wxml中通过url引用便于替换素材、扩展场景也能降低实际开发中的试错成本。1. 一个canvas typewebgl放上去真机预览直接白屏控制台只丢一句canvas is not defined——这是很多人第一次在微信小程序里接 Three.js 的现场。这个项目要解决的事情很具体在一个没有window、没有document、没有全局requestAnimationFrame的运行时里把 glb 格式的 3D 模型稳定地渲染出来还要能拖动旋转、能在低端安卓机上不掉到个位数帧率。它适合两类人手里已经有模型资产、要做商品 3D 展示或者设备结构预览的前端以及接过小程序、但被 WebGL 适配卡在半路的开发者。下面从选型一路拆到二次开发。2. 技术选型与工程结构没有 DOM 的环境里Three.js 得先被改造一遍2.1 直接npm i three会崩在哪一行先把崩溃点说清楚后面所有设计都是围绕它来的。标准版 three.js 在WebGLRenderer构造阶段就会摸document.createElementNS(http://www.w3.org/1999/xhtml, canvas)去建离屏画布TextureLoader走new Image()FileLoader走XMLHttpRequestOrbitControls直接绑addEventListener。小程序的逻辑层跑在 JSCore / V8 里上面这几样一个都没有所以不是能不能跑的问题是构造函数第一行就抛异常。小程序给的替代品是canvas typewebgl这个节点。它由渲染层创建逻辑层通过SelectorQuery().node()拿到一个 JS 对象这个对象上挂着真正的 WebGL 上下文、createImage()、requestAnimationFrame()、cancelAnimationFrame()。也就是说能力都在只是入口换了名字、换了位置。适配层干的就是这层翻译。主流做法是引官方那套threejs-miniprogram适配包它内置了一份 three 源码并暴露createScopedThreejs(canvas)返回一个作用域内的 THREE 命名空间。这个设计有两个必须知道的后果第一每个 canvas 拿到的是独立的 THREE 实例多页面、多实例互不污染这是好事。第二它和你从 npm 装的three不是同一份代码Vector3、Object3D这些类的构造函数都不同源跨作用域传对象时instanceof判断会失效merge、clone之类的操作也可能出玄学问题。血泪经验是整个项目只允许有一个 THREE 来源从适配层导出谁都不准再import three。还有一个版本陷阱。适配包里内置的 three 版本偏旧新版 API 有一批用不了renderer.outputColorSpace没有得写renderer.outputEncoding THREE.sRGBEncodingtexture.colorSpace没有得写texture.encodingWebGLRenderer.setAnimationLoop也没有动画循环得自己拿 canvas 的requestAnimationFrame转。所以从官方仓库拷 GLTFLoader 源码时不能无脑拷最新版里面但凡出现fetch、TextDecoder、createImageBitmap的地方在小程序里都是 undefined。我的建议是先用适配包自带的版本把链路跑通别一上来就追新 three。真需要新特性要么换社区里更新更勤的适配方案要么自己打补丁但绝对不能两份混用。2.2 目录结构与依赖清单工程上我一般把 3D 相关的东西全部收口到libs/和components/两层页面只负责传参不碰 THREE 对象。结构大概是这样├── miniprogram/ │ ├── app.js │ ├── app.json │ ├── pages/ │ │ └── viewer/ │ │ ├── index.js # 只做参数透传和页面生命周期 │ │ ├── index.wxml │ │ ├── index.wxss │ │ └── index.json │ ├── components/ │ │ └── model-viewer/ # 3D 逻辑全部收在这一层 │ │ ├── index.js │ │ ├── index.wxml │ │ └── index.json │ ├── libs/ │ │ ├── three.weapp.js # 适配层唯一出口 │ │ ├── GLTFLoader.js # 注入式改造版 │ │ └── MiniFileLoader.js # 替换 XHR 的文件读取器 │ └── assets/ │ └── models/ # 小体积演示模型 ├── project.config.json └── package.jsonproject.config.json里有两项必须开否则打包会出各种莫名问题{ setting: { es6: true, enhance: true, postcss: true, minified: true } }es6开的是语法转换enhance开的是增强编译包括 npm 构建后的模块处理。这两个不开require进来的适配包在某些基础库上会解析失败。另外基础库版本要拉到 2.7.0 以上canvas节点的node()查询能力才是稳定的低于这个版本res[0].node会是undefined报错信息还特别模糊。2.3 一条渲染链路的分层把整条链路竖着切开是四层理解了这个分层后面所有调试都有落点最底层是 canvas 节点它由 WXML 声明渲染层负责创建真实的 WebGL 上下文逻辑层只拿到一个句柄。往上第二层是适配层createScopedThreejs(canvas)把getContext、requestAnimationFrame、createImage这些能力包装成 three 认识的接口同时把document、window相关的调用打成空实现或者替换掉。第三层是场景层就是Scene、Camera、Light、Mesh这些标准 three 对象这一层的代码和写 H5 几乎一模一样可以照搬。最上面是业务层负责下载模型、解析 glb、处理手势、做热点标注。分层的实际价值在排查。白屏的时候先看第一层节点拿到没有黑屏但有 UI 说明第一层没问题画面空但加载回调执行了看第二、三层相机位置、光照画面在但卡看第四层模型面数、贴图、每帧分配。按这个顺序查比在几百行里瞎找快得多。3. 渲染管线拆解从 canvas 节点到第一帧画面3.1 拿到 canvas 节点时机比写法重要WXML 这一层没什么花活需要注意的是type必须显式写webgl不写就给你一个 2D 上下文后面new WebGLRenderer会直接挂canvas typewebgl idgl classgl disable-scroll{{true}} bindtouchstartonTouchStart bindtouchmoveonTouchMove bindtouchendonTouchEnd/canvasdisable-scroll是为了手势拖动时不带着页面一起滚。样式里给一个明确高度别指望内容撑开canvas 是替换元素没内容.gl width: 100vw height: 60vh display: blockJS 这一侧拿节点的代码要放在onReady不是onLoadconst { createScopedThreejs } require(../../libs/three.weapp.js) Page({ onReady() { wx.createSelectorQuery() .select(#gl) .node() .exec((res) { const canvas res res[0] res[0].node if (!canvas) { console.error(canvas node 获取失败检查基础库版本和 type 属性) return } const THREE createScopedThreejs(canvas) this.initScene(THREE, canvas) }) }, })三个参数值得说清。select(#gl)的 id 要和 WXML 对上注意别漏掉#漏了会当成标签名匹配。.node()是关键只有加了它返回的才是节点对象不加返回的是boundingClientRect那种尺寸信息很多人在这里翻车。onReady的时机是因为节点挂在渲染层页面首次渲染完成之前查询拿不到放进onLoad大概率返回null。如果这套逻辑封装在自定义组件里还要补一个.in(this)否则查询作用域是当前页面找不到组件内部的节点。3.2 渲染器、相机、光照的初始参数这一段是整篇文章里最值得抄的部分参数定错了后面全是玄学initScene(THREE, canvas) { const info wx.getSystemInfoSync() // 像素比封顶 2再高对画质提升有限对低端机是灾难 const dpr Math.min(info.pixelRatio, 2) const width info.windowWidth const height Math.round(info.windowWidth * 0.6) // 直接改 canvas 节点宽高等价于 H5 里的 canvas.width/height canvas.width width * dpr canvas.height height * dpr const renderer new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true, // 需要透明背景时打开配合 setClearColor }) renderer.setPixelRatio(dpr) // 第三个参数 updateStyle 传 false小程序节点没有 style 属性 renderer.setSize(width, height, false) renderer.setClearColor(0x000000, 0) renderer.outputEncoding THREE.sRGBEncoding const scene new THREE.Scene() const camera new THREE.PerspectiveCamera(45, width / height, 0.1, 2000) camera.position.set(0, 1.6, 4) camera.lookAt(0, 0.8, 0) // glb 里的材质多半是 MeshStandardMaterial没灯就是一片死黑 const ambient new THREE.AmbientLight(0xffffff, 0.8) const key new THREE.DirectionalLight(0xffffff, 1.2) key.position.set(3, 6, 4) const fill new THREE.DirectionalLight(0xffffff, 0.4) fill.position.set(-4, 2, -3) scene.add(ambient, key, fill) this.THREE THREE this.canvas canvas this.renderer renderer this.scene scene this.camera camera this.canvasSize { width, height } }逐个说。dpr封顶 2 是硬经验某些机型报 3.x按原值设下去渲染面积翻几倍中低端机直接掉到十几帧而且肉眼几乎看不出差别。canvas.width乘dprsetSize传的是逻辑尺寸两者配合才是清晰又不浪费。setSize的第三个参数updateStyle一定要传false因为内部会去写canvas.style.width小程序节点上根本没有style这个属性不传在某些版本上会抛异常或者尺寸错乱。相机的near设 0.1、far设 2000是因为 glb 模型单位五花八门。有的导出单位是米模型高度 1.8有的是毫米高度 1800。far给小了模型直接被远裁面切掉表现为加载成功但什么都没有这个坑后面还会单说。光照至少给一个AmbientLight打底加一个DirectionalLight出层次只有环境光模型会平得像贴纸。3.3 动画循环、生命周期与手势旋转动画循环不能用全局的requestAnimationFrame得用 canvas 节点上的那个方法而且要把 id 存下来页面卸载时取消startLoop() { const { canvas, renderer, scene, camera } this const render () { // 把 id 存起来onUnload 时要取消否则回调继续跑导致内存泄漏 this.rafId canvas.requestAnimationFrame(render) if (this.model this.autoRotate) { this.model.rotation.y 0.005 } renderer.render(scene, camera) } render() }, onHide() { if (this.rafId) { this.canvas.cancelAnimationFrame(this.rafId) this.rafId null } }, onUnload() { if (this.rafId) this.canvas.cancelAnimationFrame(this.rafId) this.disposeAll() }onHide里停循环是必须的小程序页面被切走后 WebGL 上下文还在但渲染层不再绘制继续跑render纯属白烧电。onUnload里除了停循环还要销毁资源这条单独在排查章节展开。手势旋转没有OrbitControls可用因为它内部绑的是 DOM 事件、pointerdown、wheel那一套。自己实现其实更可控二十行够了onTouchStart(e) { const t e.touches[0] // canvas 的 touch 事件里 x/y 已经是相对 canvas 左上角不用再减 rect.left this.lastTouch { x: t.x, y: t.y } }, onTouchMove(e) { if (!this.model || !this.lastTouch) return const t e.touches[0] const dx t.x - this.lastTouch.x const dy t.y - this.lastTouch.y // 0.01 是手感系数屏幕宽度 375 时大约拖动 60px 转 36 度 this.model.rotation.y dx * 0.01 // 俯仰锁在 ±45 度防止转到模型底部穿模 const nextX this.model.rotation.x dy * 0.01 this.model.rotation.x Math.max(-Math.PI / 4, Math.min(Math.PI / 4, nextX)) this.lastTouch { x: t.x, y: t.y } }, onTouchEnd() { this.lastTouch null }canvas的触摸事件有个比 H5 省事的地方e.touches[0].x和.y已经是相对 canvas 左上角的坐标不用自己算getBoundingClientRect做拖拽旋转和后面的射线拾取都直接用。系数0.01是调出来的手感值太小转不动太大一下就转飞。俯仰夹在 ±45 度内是因为大部分商品模型底部没做封闭转过去就是一片黑。4. 模型加载链路glb 文件怎么进到小程序的显存里4.1 三种文件来源的取舍模型放哪儿是这类项目第一个要拍板的问题三种主流方案各有代价方案适用体积加载速度主要限制代码包内 assets 目录单模型 2MB 以内最快不走网络主包 2MB、总包 20MB 上限不同基础库对包内路径的读取表现不一致自有 CDN wx.downloadFile无硬限制受网络影响可加缓存必须配downloadFile合法域名必须 https云开发存储无硬限制中等走云链路需开通云开发临时链接有时效包内读取看起来最省事但血泪经验是别赌兼容性。wx.getFileSystemManager()对代码包内路径的访问在不同基础库版本上时好时坏本地开发者工具能跑、真机上一读就 fail这种问题排查起来极其浪费时间。超过 1MB 的模型我一律走 CDN包内只放一个几百 KB 的演示模型保底。CDN 这条路的完整流程是先下载到临时文件再读成 ArrayBufferfunction downloadModel(url) { return new Promise((resolve, reject) { wx.downloadFile({ url, // 超过这个时长还没下来就当失败避免用户对着白屏发呆 timeout: 15000, success: (res) { if (res.statusCode ! 200) { return reject(new Error(HTTP res.statusCode)) } // tempFilePath 是本地临时路径可以直接交给 FileSystemManager resolve(res.tempFilePath) }, fail: reject, }) }) }statusCode一定要判wx.downloadFile在服务端返回 404 的时候success回调照样进来只是tempFilePath指向一个内容为错误页的文本文件后面parse会报一个完全不相干的解析错误很难定位到根因。4.2 改造 GLTFLoader把 XHR 换成小程序文件读取标准版 GLTFLoader 有三处依赖要处理FileLoader用 XHR、TextureLoader用new Image()、DRACOLoader用 Worker。glb 是二进制自包含格式几何体和贴图都打在同一个文件里所以只要把最外层的文件读取换掉后面两处基本不会触发——这也是我建议统一用 glb 而不是 gltf 外部贴图的原因。第一步是把 loader 源码包成工厂函数注入 scoped THREE// libs/GLTFLoader.js // 把官方 GLTFLoader 源码整体放进这个函数体只做一件事 // 把源码里对全局 THREE 的引用换成这里的入参最后挂到 THREE 上 module.exports function registerGLTFLoader(THREE) { // ... 原始 GLTFLoader 类定义extends THREE.Loader ... THREE.GLTFLoader GLTFLoader return THREE }第二步是替换文件读取器。GLTFLoader 内部通过this.fileLoader读主文件我们把它换成一个走FileSystemManager的实现// libs/MiniFileLoader.js module.exports function createMiniFileLoader(THREE) { class MiniFileLoader extends THREE.Loader { load(url, onLoad, onProgress, onError) { const fs wx.getFileSystemManager() fs.readFile({ filePath: url, // 不传 encoding返回的就是 ArrayBuffer success: (res) onLoad(res.data), fail: (err) onError onError(err), }) } } return MiniFileLoader }第三步在业务里串起来。注意用的方法是parse不是load因为文件已经在我们手里了async loadModel(url) { const THREE this.THREE const MiniFileLoader createMiniFileLoader(THREE) registerGLTFLoader(THREE) const loader new THREE.GLTFLoader() loader.setFileLoader(new MiniFileLoader()) const tempPath await downloadModel(url) const fs wx.getFileSystemManager() // 同步读此时文件已在本地耗时可忽略也可以换 readFile 包 Promise const buffer fs.readFileSync(tempPath) loader.parse(buffer, , (gltf) { const model gltf.scene this.fitCameraToObject(model) this.scene.add(model) this.model model this.startLoop() }, (err) { // 这里报错九成是文件不完整或者不是合法 glb console.error(gltf parse failed, err) }) }parse的第二个参数是资源基础路径传空串就行glb 内嵌资源不需要它。fitCameraToObject是个必须写的方法因为模型尺寸不可控fitCameraToObject(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.x - center.x object.position.y - center.y object.position.z - center.z // 按最大边长算距离保证模型完整入画 const maxSize Math.max(size.x, size.y, size.z) const distance maxSize / (2 * Math.tan((45 * Math.PI / 180) / 2)) * 1.5 this.camera.position.set(0, maxSize * 0.2, distance) this.camera.lookAt(0, 0, 0) }1.5是留白系数不留白模型边缘会顶到画布边界。maxSize * 0.2让相机略微抬高一点俯视角看着比平视舒服。4.3 模型规范与压缩成本上游不给规范下游怎么优化都是徒劳。我在项目里会明确写一张给美术/建模的约束表指标建议值超标后的表现三角面数单模型 5 万以内低端安卓 20fps 以下、机身发热贴图尺寸1024×1024 以内jpg 或 webp显存吃紧、首帧卡顿明显材质数量合并后控制在 10 个以内draw call 暴涨帧率抖动文件体积3MB 以内首次加载白屏时间超过 5 秒关于压缩Draco 是个绕不开的话题但得说实话DRACOLoader依赖 Worker 和 wasm 解码器小程序里 Worker 的支持有限wasm 加载路径也不一样把它跑通的成本明显高于它省下的那点体积。小模型直接不压靠减面和控制贴图就够了。真需要压优先考虑纯 JS 解码的方案或者干脆在构建期做减面不引入运行时解码器。判断标准很简单如果为了跑通压缩要改三四处 loader 源码那这笔账不划算。5. 常见问题排查五类高频故障的现象、成因与改法5.1 白屏控制台报节点为 null现象页面里除了一片白什么都没有控制台第一行是 Cannot read property node of null本文还有配套的精品资源点击获取