介绍
本文档中提及的 小程序 默认均包含相应平台的 小游戏，除非另有说明。
什么是 Three.js Platform Adapter？
Three.js Platform Adapter 是一款专为 小程序/小游戏 环境设计的 three.js 兼容库，旨在解决其在小程序环境下运行时面临的常见问题，大幅提升开发效率与体验。
本项目基于 rollup 插件实现，因此目前仅支持 rollup / vite 项目。未来将尝试发布可独立使用的版本。
项目包含三大核心模块：
- 通用兼容层：模拟实现
three.js依赖的通用 Web API，功能类似 weapp-adapter。 - 平台兼容层：基于平台 API 补全剩余 Web API，并提供
canvas获取、触摸事件透传等工具，几行代码即可初始化三维场景。 - 自动化插件：集成于
rollup/vite，自动处理与three.js相关的 worker、wasm、分包等小程序特有问题。
你为什么需要 Three.js Platform Adapter？
当你希望在小程序中 以非 WebView 方式 使用 three.js 创建三维场景时，这个项目正是为此而生。
它不仅支持 全屏 和 组件化 场景搭建，还带来以下优势：
- 高可用性：覆盖超 99% 使用场景，兼容 300+ 官方示例（详见右侧二维码）。
- 低迁移成本：熟悉
three.js的 Web 开发者可快速无缝迁移至小程序开发。 - 运行时兼容：通过运行时代理实现，无需改动源码，兼容绝大多数
three.js版本。 - 多平台支持：通过适配层支持多个小程序/小游戏平台。
- 自动化构建：自动收集并拷贝相关的
worker/wasm文件，简化构建流程。 - 分包优化：支持将依赖拆分进不同分包，避免触发体积限制。
背景与动机
在项目中实现 3D 场景的需求日益常见，three.js 以其简单的上手门槛和强大的生态系统成为主流选择，远胜于学习曲线更陡峭的 Babylon.js。相关生态中也涌现出许多优秀工具，如 @react-three/fiber。
然而，小程序的运行环境缺乏 DOM / BOM，使得 three.js 无法直接使用，给开发带来不少阻碍。
常见的三种替代方案如下：
| three.js 兼容库 | WebView 套壳 | 原生标签 (如 XR-FRAME) | |
|---|---|---|---|
| 开发成本 | 适中 | 适中 | 高 |
| 性能 | 高 | 较高 | 未知 |
| 沉浸式/局部嵌入支持 | 支持 | 不支持 | 未知 |
| 用户体验 | 优 | 一般 | 未知 |
| 与原生代码集成 | 易 | 难 | 支持 |
| 传感器支持 | 全部 | 部分 | 全部 |
其中，WebView 套壳虽实现成本最低，但在用户体验和功能限制上存在明显短板；而平台原生方案又意味着放弃 three.js 生态，开发复杂度高，难以推广。
因此，最佳方案是构建一个兼容层，让 three.js 能在小程序中原生运行。市面上已有部分先行者：
它们仍有各样的限制和不足：
| platformize-three | ThreeX | |
|---|---|---|
| 支持平台 | 多平台（需配合 rollup） | 微信（插件方式） |
| three.js 版本 |  | 插件内固定版本 |
| 分包处理 | 手动 | 手动 |
| worker 处理 | 手动 | 手动 |
| wasm 处理 | 手动 | 手动 |
| 最后更新时间 |  | 查看插件页 |
正是为了摆脱这些繁琐限制与不足，Three.js Platform Adapter 项目应运而生。
示例小程序
你可以使用微信扫码查看，它几乎包含了所有 three.js 的 webgl 分类下例子。 
还有其他问题？
请查看 常见问题解答。