快速上手
从模板开始
你可以选择以 uni-app 或 weapp-vite 作为基础框架,从官方模板开始快速搭建项目。模板中已包含必要的插件配置与示例代码,便于直接开发。
使用 uni-app 模板
shell
npx degit minisheeep/threejs-miniprogram-template#uni-ts my-project
shell
npx degit minisheeep/threejs-miniprogram-template#uni-ts-tresjs my-project
shell
npx degit minisheeep/threejs-miniprogram-template#uni-ts-r3f my-project
使用 weapp-vite 模板
shell
npx degit minisheeep/threejs-miniprogram-template#weapp-vite my-project
shell
npx degit minisheeep/threejs-miniprogram-template#weapp-vite-tresjs my-project
shell
npx degit minisheeep/threejs-miniprogram-template#weapp-vite-r3f my-project
使用小游戏模板
shell
npx degit minisheeep/threejs-miniprogram-template#wechat-game-ts my-project
如遇下载失败,也可前往 GitHub 模板仓库 选择对应分支手动下载。
如需更多框架模板支持,欢迎加入社区交流群反馈需求。
集成到已有项目中
当前仅支持在基于 rollup
或 vite
的项目中使用,后续将提供不依赖构建工具的版本。
1. 添加私有源配置
由于相关依赖包暂未发布至 npm 官方仓库,请先在项目根目录创建或修改 .npmrc
文件,添加以下内容:
text
@minisheep:registry=https://npm.minisheep.cn
2. 安装核心依赖
执行以下命令安装兼容运行时环境及插件功能所需的依赖包:
shell
pnpm i @minisheep/mini-program-polyfill-core @minisheep/three-platform-adapter
shell
npm i @minisheep/mini-program-polyfill-core @minisheep/three-platform-adapter
shell
yarn add @minisheep/mini-program-polyfill-core @minisheep/three-platform-adapter
这两个依赖分别用于:
- 补全小程序中缺失的 DOM / BOM / Web API;
- 提供辅助构建的 Rollup 插件。
详细介绍见文档:mini-program-polyfill-core 和 three-platform-adapter。
3. 配置构建插件
在你的 vite.config.js
或 rollup.config.js
中引入并注册插件:
js
import threePlatformAdapter from '@minisheep/three-platform-adapter/plugin';
export default {
plugins: [
// ...
threePlatformAdapter() // 可选配置项见文档说明
// ...
]
}
4. 添加平台适配代码
根据你使用的小程序平台,在项目入口文件引入对应 polyfill:
js
import '@minisheep/mini-program-polyfill-core/wechat-polyfill';
import '@minisheep/three-platform-adapter/wechat';
js
// 更多平台适配支持即将推出
至此,three.js
的开发环境就搭建完成了!
你可以开始像在 Web 一样创建三维场景。不过由于小程序平台的差异,仍有一些注意事项,请继续阅读:创建场景指南。