从零到一，微信小程序三维开发实战指南

打开小程序后台，翻到「组件」那一栏，很多人第一眼看到的是密密麻麻的标签列表，滑到底部才发现那个不起眼的「canvas」和「web-view」。但你真要做三维的东西，光靠这两个远远不够。我踩过的坑比你们想象的多，最开始我在本地用Three.js写得好好的，一塞进小程序就各种报错，白屏、贴图丢失、内存爆掉，折腾了整整三天才找到门路。今天这篇文章，就把我从零到一摸索出来的微信小程序三维开发路径，完完整整告诉你。

先泼一盆冷水：微信小程序本身不提供原生3D能力。你看到的那些炫酷的3D商品展示、虚拟试穿、互动小游戏，底层全是绕道实现的。最主流的方案有两个：一是用web-view把H5页面嵌进来，在网页里跑Three.js；二是用小程序自带的canvas 2D接口，配合第三方库做伪3D。前者简单但加载慢，体验割裂；后者性能好但限制多，很多效果做不出来。我推荐你走第三条路：用小程序官方提供的Canvas 3D接口，配合ECharts的GL版本或者Three.js的适配版，这才是真正意义上能在微信生态里跑起来的3D方案。

具体怎么落地？我拿一个实际项目举例：给一个家具品牌做沙发3D展示。第一步，你得在小程序后台申请「canvas」组件的type="webgl"权限，这个必须在app.json里配置好，不然接口直接不认。然后引入适配好的threejs-miniprogram库，这是官方团队维护的，专门解决小程序环境里WebGL的兼容问题。安装方式很简单，npm install threejs-miniprogram，然后在代码里import就行。这里有个关键点：小程序的canvas不认window对象，所以你不能直接用原版Three.js，必须用这个适配版，否则一运行就报「window is not defined」。

代码写起来其实跟网页版很像。创建场景、加相机、放模型、加灯光，流程完全一样。但有几个坑必须提前规避。第一个坑是贴图加载：小程序里不能直接写图片路径，得用wx.getImageInfo拿到临时路径，再传给纹理加载器。第二个坑是模型格式：glTF格式在小程序里兼容性最好，但文件体积不能太大，最好控制在2MB以内，超出的话加载时间会让你怀疑人生。第三个坑是性能：小程序的渲染线程跟逻辑线程是分开的，你如果频繁操作场景里的对象，很容易触发内存泄漏，所以一定要记得在onHide生命周期里调用renderer.dispose()清理资源。

我建议你从最简单的旋转立方体开始练手。不要一上来就做复杂场景，先把基础API跑通。写一个页面，放一个canvas，设置type="webgl"，然后在onReady里初始化Three.js场景。创建立方体、加一个环境光、把相机放在合适位置，然后通过requestAnimationFrame让立方体自动旋转。这一步跑通了，你就已经掌握了小程序3D的80%核心逻辑。剩下的就是往场景里加东西：加模型、加交互、加动画。交互这一块，小程序里有touch事件，你可以监听touchstart、touchmove来实现拖拽旋转，效果跟网页版一模一样。

说到交互，这里有个很多新手不知道的技巧。小程序的三维场景里，你不能直接用three.js的Raycaster做射线检测，因为小程序的触摸事件返回的坐标跟canvas的坐标系不一样。你得手动做一次坐标换算：把触摸点的小程序坐标，减去canvas左上角的偏移量，再乘以canvas宽度和实际渲染宽度的比例，才能得到正确的三维坐标。这个换算公式我在项目里调试了快两个小时，翻源码才找到答案。你要是绕过了这个坑，至少能省下半天时间。

再聊一下性能优化。小程序的包体积限制是2MB，这对3D项目来说非常致命。我的建议是：模型文件不要放在本地，全部放CDN，用wx.downloadFile先下载到本地再加载。代码层面，尽量用ES6的模块化写法，按需引入Three.js的各个模块，别把整个库都打包进去。还有纹理压缩：小程序支持WebP格式，一张1MB的PNG纹理换成WebP能压到200KB，加载速度提升明显。内存管理也要重视，场景里的模型用完就remove，材质和几何体记得调dispose()释放GPU资源。

说说调试工具。小程序开发者工具里是可以调试3D场景的，但有个问题：真机上跑的效果跟模拟器差别很大，特别是GPU性能方面。我的经验是，每写一段代码就真机预览一次，别等全部写完再测。还有，微信开发者工具的「调试器」面板里有个「WXML」标签页，你可以在里面看到canvas节点的实时属性，这对排查坐标问题特别有用。另外一个隐藏技巧：在代码里加console.log打印相机位置和模型的position，比肉眼看屏幕要准确得多。

从零到一的过程很痛苦，但一旦跑通了第一个旋转立方体，后面的路就顺了。三维开发在小程序里不是禁区，只是绕了几个弯。你只要把基础API吃透，搞定坐标换算和性能优化这两座大山，剩下的就是把网页版的Three.js经验迁移过来。我见过不少开发者用这套方案做出了很惊艳的AR试戴、3D产品展示、甚至是小游戏。工具和方案都是现成的，缺的只是你动手写那第一行代码的勇气。现在，打开你的开发者工具，创建一个新页面，放一个canvas，开始你的第一个小程序3D项目吧。