threejs-miniprogram

threejs-miniprogram#

资源概述#

threejs-miniprogram 是微信官方小程序团队维护的 Three.js 小程序适配版本。它通过 createScopedThreejs(canvas) 将 Three.js 的核心模块绑定到小程序的 WebGL Canvas 节点上，使开发者能够在微信小程序中实现 3D 场景渲染、模型加载、动画和粒子效果。

GitHub：wechat-miniprogram/threejs-miniprogram（788 ⭐ / 237 forks / MIT）
npm：threejs-miniprogram@0.0.8（月下载 ~1,200）
Three.js 版本：r108.0（稳定锁定，升级需 fork）
官方维护：微信小程序团队（wechat-miniprogram 组织）
状态：维护模式（稳定适配，不频繁更新；Three.js 本身迭代到 r160+，但小程序适配版本停留在 r108）

该库是微信小程序 3D 渲染的事实标准方案。虽然 Three.js 主线已远超 r108，但 r108 已覆盖绝大多数小程序 3D 场景需求（模型加载、光照、材质、动画、粒子），且小程序 WebGL 环境的特殊性使得直接升级主线 Three.js 并不简单。

设计规范#

Canvas 类型#

小程序中使用 WebGL 必须指定 <canvas type="webgl">（旧版基础库使用 <canvas canvas-id="webgl">），通过 wx.createSelectorQuery().select('#webgl').node() 获取 Canvas 节点对象。

scoped THREE 设计#

createScopedThreejs(canvas) 返回的 THREE 对象是与特定 Canvas 绑定的，不同于 Web 端的全局 window.THREE。如果页面有多个 WebGL Canvas，需要为每个 Canvas 创建独立的 THREE 实例。

包体积考量#

Three.js 核心库体积较大（约 600KB），建议：

放入分包加载，避免占用主包 2MB 限额
按需引入 Loader（如仅用 GLTFLoader 则不引入 OBJLoader）
使用微信开发者工具的代码依赖分析确认实际打包大小

审核规范#

作为工具库本身无需审核。但使用 Three.js 的小程序在提审时需注意：

性能：3D 场景可能导致低端设备卡顿或 OOM，需做降级处理
包体积：确认构建后包大小不超过限制（主包 2MB / 总包 20MB）
WebGL 兼容：部分旧机型不支持 WebGL，需检测并提示

开发指南#

快速上手#

1. 安装

code

npm install --save threejs-miniprogram

在微信开发者工具中：工具 → 构建 npm。

2. WXML

code

<canvas type="webgl" id="webgl" style="width: 100%; height: 100%;"></canvas>

3. JS — 创建一个旋转立方体

code

import { createScopedThreejs } from 'threejs-miniprogram'

Page({
  onReady() {
    wx.createSelectorQuery()
      .select('#webgl')
      .node()
      .exec((res) => {
        const canvas = res[0].node
        const THREE = createScopedThreejs(canvas)

        // 渲染器
        const renderer = new THREE.WebGLRenderer({ canvas, antialias: true })
        renderer.setSize(canvas.width, canvas.height)

        // 场景与相机
        const scene = new THREE.Scene()
        const camera = new THREE.PerspectiveCamera(75, canvas.width / canvas.height, 0.1, 1000)
        camera.position.z = 5

        // 立方体
        const geometry = new THREE.BoxGeometry(1, 1, 1)
        const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 })
        const cube = new THREE.Mesh(geometry, material)
        scene.add(cube)

        // 渲染循环
        function animate() {
          canvas.requestAnimationFrame(animate)
          cube.rotation.x += 0.01
          cube.rotation.y += 0.01
          renderer.render(scene, camera)
        }
        animate()
      })
  }
})

常见陷阱#

requestAnimationFrame：小程序中不能用 window.requestAnimationFrame，必须使用 canvas.requestAnimationFrame（Canvas 节点的方法）。
图片纹理：小程序的图片加载方式与 Web 不同，需使用 canvas.createImage() 而非 new Image()。纹理加载需配合适配。
THREE 不在全局：返回的 THREE 是 scoped 的，不能与全局 THREE 混用。使用 Three.js 配套库（如 controls / loaders）时需手动传入 THREE。
dpr 处理：小程序 Canvas 需手动处理设备像素比（renderer.setPixelRatio(wx.getSystemInfoSync().pixelRatio)）。
销毁：页面 onUnload 时需取消 requestAnimationFrame 并释放 WebGL 资源，否则内存泄漏。

加载 3D 模型#

code

import { createScopedThreejs } from 'threejs-miniprogram'

// GLTFLoader 需从 three/examples/jsm/loaders/GLTFLoader.js 单独引入
// 并传入 scoped THREE
const loader = new THREE.GLTFLoader()
loader.load(modelUrl, (gltf) => {
  scene.add(gltf.scene)
})

生态资源#

社区资源#

官方示例项目 — 含基础渲染、模型加载、粒子效果等示例
Three.js 官方文档 — r108 版本 API 参考
小程序 Canvas/WebGL 文档

版本更新#

v0.0.8（当前 npm 最新）：稳定适配 Three.js r108.0
仓库状态：维护模式，微信官方不定期修复适配问题（接受 issue 和 PR）
Three.js 主线：已迭代至 r160+，但小程序版本不跟进主线（因适配工作量巨大且 r108 覆盖大部分需求）
最后核实：2026-07-23（npm 月下载 ~1,200，仍有活跃用户群体）

特性

详细文档