介绍

各页文档中 小程序 部分指代未特殊说明皆包含对应平台 小游戏 部分。

Three.js Platform Adapter 是什么？

顾名思义，Three.js Platform Adapter 是一款专为 小程序 / 小游戏 设计的 three.js 兼容库，它用于解决小程序在开发 3D 场景时普遍遇到的一些问题，增加开发者的开发效率和体验。

本项目的相关处理都是依托于 rollup 插件实现的，所以仅能在 rollup / vite 项目中使用，后续会尝试发布可以独立使用的版本。

本项目由三部分组成：

通用兼容层：对 three.js 中使用到的通用 Web API 进行了实现，类似于 weapp-adapter。
平台兼容层：使用平台 API 补全剩余的 Web API, 以及提供一些获取 canvas, 透传触摸事件的工具函数，使开发者仅需寥寥数行代码就能像 web 中使用 three.js 一样搭建三维场景。
自动化插件：一个支持 rollup / vite 中使用的插件，自动处理 three.js 相关代码，使开发者免于烦恼 worker / wasm / 分包 等小程序特有的问题。

本项目能够帮助你以全屏 / 组件化 的形式使用 three.js，如果你需要在满足核心需求的前提下还拥有以下更完善的功能，那么本项目很适合你：

高可用，完美覆盖 99% 的使用场景，支持 300 余种官方示例。详见右侧小程序二维码。
低负担, 使在 web 中有 three.js 开发经验的开发者能够无缝切换到小程序开发，或将已有的 three.js 场景直接迁移到小程序中来，不必考虑小程序本身的 api 差异。
运行时兼容，采用运行时代理而非修改源代码的方式实现兼容层，理论上支持绝大部分 three.js 版本，减少后续升级维护难度。
多平台支持，搭配不同平台的兼容层，支持在多种小程序/小游戏平台使用。
自动化，自动收集/拷贝使用到的 worker / wasm 到小程序目录，减少琐碎的工作，增加开发效率。
分包优化，健全的处理机制能够将使用到的 jsm 模块分散放置在不同的分包当中，避免触发包大小限制。

在日常开发中，难免遇到需要前端开发者去实现三维场景的需求，这时候比较热门的选择一般是 three.js 和 Babylon.js 。

和 Babylon.js 相比， three.js 拥有较为简单的学习成本和丰富的生态，也诞生许多基于它的优秀框架，例如 @react-three/fiber。所以 three.js 一般是前端开发者开发 3D 场景首要技术选择。

但由于小程序特殊的背景和生态，它的执行环境里并没有 DOM / BOM API，这就导致了 three.js 并不能直接小程序中使用，需要变着法子去使用它，给开发者徒增了不少工作量。

经过一番调查，我整理了小程序中搭建 3D 场景比较常见的 3 种方式及其相应的优缺点和局限性:

其中使用 web 开发直接 webview 套壳的方式是最简单也是效率最高的，但它是用户体验对开发成本的一种妥协，并限制了许多使用场景。

而选用平台原生 3D 方案意味着放弃了 three.js 丰富的生态，给自己和公司开发预算上强度，并不适合普通公司使用。

所以最终选用的方案是兼容处理 three.js 使其能够在小程序环境中执行，这方面市面上也有许多优秀先行者，例如： platformize-three （前身：three-platformize）和 ThreeX。但它们仍有各样的限制和不满足的功能：

不满于这些限制和功能，所以才诞生了本项目。

你可以使用微信扫码查看，它几乎包含了所有 three.js 的 webgl 分类下例子。 wechat-mp-code