简介：这份资源面向希望在微信小程序中实现3D可视化效果的开发者，尤其适合已掌握JavaScript基础、想进一步学习three.js集成的中级前端人员。它围绕小程序加载外部3D模型这一技术难点，提供可运行的工程示例，帮助读者理解场景初始化、模型加载与渲染循环等关键环节。压缩包共11个文件，约167KB，包含4个js脚本、4个json配置、1个wxml模板、1个wxss样式及1个md说明文档，分别承担逻辑实现、页面结构、样式与项目配置等职责，目录按小程序工程规范组织，便于直接导入开发者工具对照学习。目前已有3207人学习下载，说明该主题在小程序开发群体中具有较高关注度。读者可从中获得three.js在小程序环境下的接入思路、外部模型加载的完整代码骨架，以及动画循环与资源释放的实践参考，适合作为3D小程序入门的对照样例。
1. 从一次“模型加载不出来”的现场说起
去年接了个需求，要在微信小程序里展示一个可旋转、可缩放的产品三维模型，客户还要求模型文件放在服务端，随时能换。第一反应是找现成方案，结果翻了一圈发现：小程序原生并不支持直接加载 glTF、OBJ 这类外部模型文件，<canvas>的 WebGL 上下文又和浏览器里那套用法有出入。真正跑通之后回头看，miniprogramThree这个项目就是干这件事的——把 Three.js 塞进小程序，再解决外部模型文件的加载链路。它适合两类人：一类是手里有现成 3D 模型、想在小程序里做展示的开发者；另一类是已经会用 Three.js、但被小程序环境卡住的熟手。下面按“它怎么组织、怎么跑起来、怎么改”的顺序拆。
2. 项目结构与技术选型：Three.js 如何落进小程序
2.1 为什么是 Three.js 加适配层，而不是原生 WebGL
小程序里的渲染能力和浏览器不完全一致，最直接的差异是拿不到标准的document、window，也没有XMLHttpRequest那套完整实现。Three.js 本身依赖这些全局对象，所以不能直接import进来就用。这个项目的思路是引入一层适配：用小程序提供的canvas节点创建 WebGL 上下文，再把 Three.js 需要的全局对象补齐，最后让 Three.js 跑在这个“伪浏览器”环境里。
常见做法是在入口处做一次环境注入，把window、document的最小实现挂到全局，再加载 Three.js。这样 Three.js 内部的WebGLRenderer就能拿到 canvas，TextureLoader、FileLoader也能走通。选 Three.js 而不是手写 WebGL 的理由很实际：模型解析、相机控制、光照材质这些轮子 Three.js 都有，自己写一遍不划算，适配层虽然麻烦但只写一次。
2.2 目录结构长什么样
项目按小程序标准结构组织，核心目录大致如下：
miniprogramThree/ ├── app.js 小程序入口，做全局环境注入 ├── app.json 页面注册与窗口配置 ├── pages/ │ └── index/ │ ├── index.js 页面逻辑，初始化场景与加载模型 │ ├── index.wxml 承载 canvas 的模板 │ └── index.wxss 画布尺寸样式 ├── libs/ │ ├── three.min.js Three.js 核心库 │ └── adapter.js 小程序环境适配层 └── models/ 本地模型与贴图资源libs目录是整个项目的关键，adapter.js负责抹平环境差异，three.min.js是未改动的官方构建产物。pages/index是唯一的演示页，把“创建 canvas → 初始化渲染器 → 加载模型 → 启动渲染循环”这条链路完整走了一遍。models放本地资源，方便先跑通再换成远程地址。
2.3 适配层做了什么
适配层的核心是补全局对象和接管资源加载。下面这段是环境注入的典型写法：
// libs/adapter.js // 在小程序里伪造 Three.js 需要的最小全局环境 const mockWindow = { devicePixelRatio: 1, innerWidth: 375, innerHeight: 667, requestAnimationFrame: (cb) => setTimeout(cb, 16), cancelAnimationFrame: (id) => clearTimeout(id), URL: { createObjectURL: () => '', revokeObjectURL: () => {} } }; // 把 window 挂到全局，Three.js 内部会读 window if (typeof global.window === 'undefined') { global.window = mockWindow; } // document 只需要 createElementNS 返回一个带 getContext 的假 canvas if (typeof global.document === 'undefined') { global.document = { createElementNS: () => ({ getContext: () => null, style: {} }), createElement: () => ({ style: {} }) }; } module.exports = mockWindow;这段代码的逻辑是：Three.js 在初始化渲染器、创建纹理、处理动画帧时会访问window和document，小程序没有这些对象，直接引用就报undefined。mockWindow提供了requestAnimationFrame的降级实现（用setTimeout模拟），保证渲染循环能转起来；document.createElementNS返回一个占位对象，避免 Three.js 在创建离屏 canvas 时崩溃。参数上，devicePixelRatio和innerWidth/innerHeight按真机尺寸调整，否则画面会糊或者比例不对。
提示：适配层只补 Three.js 实际用到的属性，不要一股脑把浏览器 API 全模拟一遍，补多了反而容易和真机行为冲突。
3. 跑起来：从 canvas 初始化到模型上屏
3.1 页面模板与 canvas 节点获取
小程序里 canvas 不是 DOM 节点，得用wx.createSelectorQuery拿到节点实例，再取node和getContext。模板里先声明一个 canvas：
<!-- pages/index/index.wxml --> <canvas type="webgl" id="webgl" style="width: 100%; height: 100vh;" bindtouchstart="onTouchStart" bindtouchmove="onTouchMove" ></canvas>type="webgl"是关键，声明用 WebGL 上下文而不是 2D。bindtouchstart和bindtouchmove用来接管手势，后面做模型旋转和缩放。样式上给足宽高，否则 canvas 默认尺寸很小，模型会挤在角落。
页面逻辑里获取节点：
// pages/index/index.js Page({ onReady() { wx.createSelectorQuery() .select('#webgl') .node() .exec((res) => { const canvas = res[0].node; // 拿到 canvas 后交给渲染器初始化 this.initThree(canvas); }); } });onReady而不是onLoad，因为要等节点渲染完成才能查到。exec回调里的res[0].node就是 canvas 实例，把它传给initThree。这一步翻车的常见原因是页面还没渲染完就查询，拿到null，所以生命周期选对很重要。
3.2 渲染器、场景、相机三件套
拿到 canvas 后初始化 Three.js 的基础对象：
// pages/index/index.js const THREE = require('../../libs/three.min.js'); require('../../libs/adapter.js'); initThree(canvas) { const renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true, alpha: true }); renderer.setSize(canvas.width, canvas.height); renderer.setPixelRatio(1); const scene = new THREE.Scene(); scene.background = new THREE.Color(0xf0f0f0); const camera = new THREE.PerspectiveCamera( 45, canvas.width / canvas.height, 0.1, 1000 ); camera.position.set(0, 0, 5); // 环境光加平行光，避免模型全黑 scene.add(new THREE.AmbientLight(0xffffff, 0.8)); const dirLight = new THREE.DirectionalLight(0xffffff, 0.6); dirLight.position.set(1, 1, 1); scene.add(dirLight); this.renderer = renderer; this.scene = scene; this.camera = camera; this.animate(); }WebGLRenderer传入 canvas 实例，antialias开抗锯齿让边缘平滑，alpha允许背景透明。setPixelRatio(1)在小程序里比浏览器保守，设太高会吃性能。相机用透视相机，45是视野角度，0.1和1000是近远裁剪面，模型超出这个范围会被裁掉。光照部分环境光保证基础亮度，平行光给模型立体感，缺了平行光模型会显得扁平。
3.3 加载外部模型：Loader 与路径处理
模型加载是项目的核心。Three.js 的GLTFLoader在浏览器里靠fetch或XMLHttpRequest拉文件，小程序里得换成wx.request或wx.downloadFile。常见做法是先用wx.downloadFile把模型下到本地临时路径，再让 Loader 读本地文件：
// pages/index/index.js loadModel(url) { wx.downloadFile({ url: url, success: (res) => { if (res.statusCode !== 200) return; const loader = new THREE.GLTFLoader(); loader.load( res.tempFilePath, (gltf) => { const model = gltf.scene; model.scale.set(1, 1, 1); this.scene.add(model); this.model = model; }, undefined, (err) => { console.error('模型解析失败', err); } ); }, fail: (err) => { console.error('下载失败', err); } }); }wx.downloadFile的url必须是配置过合法域名的地址，否则直接失败。下载成功后res.tempFilePath是本地临时路径，GLTFLoader.load读这个路径就能解析。gltf.scene是模型根节点，scale按实际模型尺寸调，很多模型导出时单位是米，直接放进来可能大得离谱或小得看不见。错误回调里打印err，解析失败通常是模型文件损坏或贴图路径不对。
注意：glTF 模型如果带外部贴图，贴图路径是相对模型文件的，下载单个
.gltf不够，得把.bin和贴图一起下，或者直接用打包好的.glb单文件格式，省掉路径问题。
3.4 渲染循环与手势交互
渲染循环用适配层里的requestAnimationFrame驱动：
// pages/index/index.js animate() { const loop = () => { this.renderer.render(this.scene, this.camera); this.rafId = setTimeout(loop, 16); }; loop(); }, onTouchMove(e) { if (!this.model) return; const touch = e.touches[0]; const dx = touch.clientX - this.lastX; const dy = touch.clientY - this.lastY; // 横向拖动绕 Y 轴转，纵向拖动绕 X 轴转 this.model.rotation.y += dx * 0.01; this.model.rotation.x += dy * 0.01; this.lastX = touch.clientX; this.lastY = touch.clientY; }循环里每帧调renderer.render，用setTimeout模拟 16ms 间隔，约 60 帧。手势部分记录上一次触点坐标，算出差值映射到旋转角度，0.01是灵敏度系数，调大转得快、调小更精细。onTouchStart里要初始化lastX和lastY，否则第一次拖动会跳变。页面卸载时记得clearTimeout(this.rafId)，不然循环还在跑，白白耗电。
4. 避坑与排查：模型加载链路上的五个真实坑
4.1 现象：canvas 查到的是 null
原因通常是生命周期用错，在onLoad里查询节点，此时页面还没渲染完。解决是把查询挪到onReady，或者用wx.nextTick包一层。另外select的 id 要和模板里一致，大小写都算。
4.2 现象：模型下载成功但解析报错
多半是模型格式和 Loader 不匹配，比如用GLTFLoader去读 OBJ 文件。先确认文件扩展名，glTF 用GLTFLoader，OBJ 用OBJLoader加MTLLoader。还有一种情况是.gltf引用的.bin没一起下载，解析到一半找不到缓冲区就崩，换成.glb单文件最省心。
4.3 现象：模型全黑或者只有轮廓
光照没配好。只有环境光时模型没有明暗变化，看起来像贴图丢了；只有平行光时背光面全黑。解决是环境光加平行光组合，环境光强度0.6到0.8，平行光0.5左右，再按模型朝向调平行光位置。材质如果是MeshStandardMaterial，还需要环境贴图才有反射效果。
4.4 现象：真机上画面模糊或比例失调
setPixelRatio设成了window.devicePixelRatio，但适配层里这个值是写死的1，和真机实际像素比不一致。解决是初始化时用wx.getSystemInfoSync().pixelRatio取真实值传给渲染器，同时setSize用 canvas 的实际宽高而不是屏幕宽高。
4.5 现象：切页面后内存暴涨
渲染循环没停，或者模型、纹理没释放。页面onUnload里要clearTimeout停循环，再对geometry、material、texture逐个调dispose()，最后renderer.dispose()。小程序对内存比较敏感，反复进出页面不释放，几次之后就卡死。
5. 二次开发：换模型、加交互、控性能的改造思路
拿到这个项目之后，最常改的三处是模型来源、交互方式和性能策略。换模型最直接，把loadModel的url换成自己的地址，注意域名要加进小程序的合法域名列表，本地调试可以在开发者工具里勾选不校验域名。模型尺寸不一致时，别急着改scale，先用new THREE.Box3().setFromObject(model)算出包围盒，再按包围盒尺寸自动缩放，这样换任何模型都能自适应：
// 自动适配模型尺寸到视野内 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 targetSize = 3; // 期望占据的视野尺寸 model.scale.setScalar(targetSize / maxDim);Box3算出模型的实际包围范围，maxDim取最长边，targetSize / maxDim得到缩放系数，这样不管模型原始单位是毫米还是米，上屏大小都一致。加交互的话，除了旋转，还可以接双指缩放：在onTouchMove里判断e.touches.length === 2，算两指距离变化映射到camera.position.z，注意加个上下限防止穿模。
性能上，模型面数高的时候真机会掉帧。常见做法是让美术导出时减面，或者在加载后遍历model.traverse关掉不必要的阴影和材质特性。下面这张表是我一般会先看的几个参数：
| 参数 | 建议值 | 说明 |
|---|---|---|
setPixelRatio | 真机 pixelRatio，上限 2 | 太高吃性能 |
| 渲染帧间隔 | 16ms | 约 60 帧，卡就放宽到 33ms |
| 模型面数 | 5 万以内 | 超过考虑减面或分块加载 |
| 贴图尺寸 | 1024 以内 | 大贴图占内存 |
改完一定要在真机上验证，开发者工具的模拟器和真机在 WebGL 实现上有差异，模拟器跑得动不代表真机不卡。我一般会开着小程序的性能面板看帧率和内存曲线，模型加载前后各看一次，内存不回落就是有东西没释放。从那以后我每次接 3D 展示需求，都先把“模型格式、贴图是否内嵌、目标机型”这三件事问清楚再动手，省掉后面反复返工。希望帮到你。
本文还有配套的精品资源，点击获取
