Skip to content

快速上手

使用本工具前建议了解

从模板开始

你可以选择以 uni-appweapp-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 模板仓库 选择对应分支手动下载。

如需更多框架模板支持,欢迎加入社区交流群反馈需求。


集成到已有项目中

当前仅支持在基于 rollupvite 的项目中使用,后续将提供不依赖构建工具的版本。

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-corethree-platform-adapter

3. 配置构建插件

在你的 vite.config.jsrollup.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 一样创建三维场景。不过由于小程序平台的差异,仍有一些注意事项,请继续阅读:创建场景指南