MengTo/threeui · 上手攻略
- 仓库：MengTo/threeui
- 链接：https://github.com/MengTo/threeui
- 分类：前端组件库 · 3D/WebGL · React
- 作者：Tom
- 更新：2026-08-27
这是什么
ThreeUI 是设计师/开发者 Meng To（DesignCode.io 创始人）开源的 React + Three.js 组件库，主打可复制粘贴的 3D 网页组件，覆盖 Procedural 3D Hero Section、背景、按钮、图标、过渡动画等场景。与传统 Three.js 项目不同，ThreeUI 的每个组件都是独立可运行的代码块，内置实时可调节的控制面板（Controls、Variant Picker），开发者可以直接把代码拷贝进自己的 React 项目，修改颜色、灯光、运动参数。
项目分两条线：
- Community（免费开源）：本仓库，MIT 许可证，包含 50 个父级组件、111 条路由、141 个免费变体记录，以及 23 个单例组件（共 164 个可浏览结果）
- Pro（商业闭源）：通过 @designcodeio/threeui-cli 认证下载，包含 Pro 组件源码
⚠️ 官方 README 标注 2026-08-26 网站日均约 90,000 次浏览（directional traffic context，非保证数据）。
解决什么问题
前端开发者想在 React 网站里加 3D 效果，传统路径是： 1. 学 Three.js 底层 API 2. 手写 Shader 语法 3. 处理 WebGL 上下文、GPU 内存泄漏 4. 自己实现响应式和动画逻辑
ThreeUI 把上述路径压缩为：挑组件 → npm install → import → 改参数。每个组件 100–200 KB，全部用 procedural JS 写成（即代码生成而非资源文件），通过 Three.js 实例化渲染。同时配套 AI Agent Skill，Agent 可以帮你定制组件而保持视觉效果。
同类痛点竞品对比：
| 方案 | 优势 | 劣势 |
|---|---|---|
| react-three-fiber | 完整 R3F 生态，灵活 | 需懂 Three.js API |
| @react-three/drei | 工具函数丰富 | 非组件级封装 |
| ThreeUI | 组件级 copy-paste，可调参数，AI Agent 定制 | 仅 React，组件数量有限，Pro 闭源 |
| shadcn/ui | copy-paste 工作流一致 | 无 3D 能力 |
快速安装
前置依赖（需已存在项目）：
node >= 18
npm 或 pnpm
React 项目（Next.js / Vite 均可）
安装 Community npm 包：
npm install @designcodeio/threeui
# 或
pnpm add @designcodeio/threeui
安装全局样式（必须，否则无默认主题）：
// 在你的 App.tsx 或 layout.tsx 顶部加这一行
import "@designcodeio/threeui/style.css";
最小可跑示例（官方 README 原文）：
import { AtTheHorizon } from "@designcodeio/threeui";
import "@designcodeio/threeui/style.css";
export function Hero() {
return <AtTheHorizon />;
}
子路径导入（减少打包体积）：
import { AtTheHorizon } from "@designcodeio/threeui/components/AtTheHorizon";
⚠️ 某些组件（如全屏 HTML 文档类组件）依赖运行时资产文件，需将 node_modules/@designcodeio/threeui/lib-dist/assets/ 下的文件复制到项目 public/ 目录，或通过 sourceUrl / assetBaseUrl prop 覆盖路径。
核心用法
开发预览（本地运行完整 ThreeUI 展示）
git clone https://github.com/MengTo/threeui.git
cd threeui
npm install
npm run dev
# 打开 http://localhost:3000（默认 Next.js 端口）
生产构建检查
npm run build
包含边界检查、类型检查和生产构建三道卡口。
Pro 组件下载（需 ThreeUI Pro 订阅）
# 登录（OAuth PKCE，session 存在 owner-only 权限目录）
npx @designcodeio/threeui-cli login
# 下载指定 Pro 组件源码
npx @designcodeio/threeui-cli add cross-beam
# 查看所有可用选项
npx @designcodeio/threeui-cli --help
组件同步维护（仓库维护者用）
如果你持有完整 ThreeUI 私有仓库，可以把 Community 子集同步到本仓库：
npm run sync:community -- /path/to/main-threeui
同步后生成三个文件：
- public/community-sync-report.json — 各组件变体/控件数量对比
- public/source-code.json — Code Tab 展示用的 Community 源码包
- src/data/shaders.tsx — Community 专用 catalog 和 renderer 导入
典型适用场景
- Landing Page Hero 区域：3D 动态背景、悬浮元素、品牌动画，直接提升页面质感
- 产品展示页：3D 旋转模型、交互式图表展示
- 品牌动画图标：Procedural 生成的可编程 SVG/Three.js 图标，可随主题色变化
- Agent 建站流水线：开发者/AI Agent 通过 copy-paste 快速组装 3D 页面，无需手写 WebGL
- Demo / Portfolio：设计师展示 3D 交互作品，可在线调节参数给客户看效果
坑与注意
- ⚠️ npm 包版本未在 README 中标注：无法确认当前 npm 最新版本，建议
npm info @designcodeio/threeui查看，或指定"@designcodeio/threeui": "latest"安装 - GPU 内存泄漏风险：Agent 编辑 Three.js 组件时容易泄漏 GPU 内存（评论区有用户提及），需要手动处理
geometry.dispose()和material.dispose() - Pro/Community 边界需注意：部分组件在 Pro 版，npm 包只有 Community；不要误以为完整组件集都在 npm 里
- 资产文件路径：运行时依赖
public/目录放资产文件，ssg/ssr 场景下可能需要额外配置 - Last commit 时间未标注：README 无版本号或 npm 最新版本号；实际以 npm 安装结果为准，GitHub 仓库可能有延迟
- Three.js 版本锁定：README 未说明 three.js 依赖版本；建议查看
package.json的peerDependencies或dependencies确认
与同类对比
| 维度 | ThreeUI | react-three-fiber | @react-three/drei | 传统 Three.js |
|---|---|---|---|---|
| 上手门槛 | 低 | 中 | 中 | 高 |
| 组件化程度 | 高（copy-paste） | 低（API 级） | 中（工具函数） | 无 |
| 3D 深度控制 | 低（黑盒组件） | 高 | 高 | 最高 |
| AI Agent 集成 | 有（官方 skill） | 无 | 无 | 无 |
| 许可证 | MIT（Community） | MIT | MIT | MIT |
| 组件数量 | ~164 个可浏览 | 取决于手写 | 取决于手写 | 取决于手写 |
结论：ThreeUI 适合不想深入 Three.js API，想快速在 React 里加 3D 效果的场景。如果需要精细控制 WebGL 行为，选 react-three-fiber；如果需要 AI Agent 辅助定制，选 ThreeUI。
一句话推荐结论
ThreeUI 把 Three.js 的复杂度封装到组件层，让 React 开发者能像用 shadcn/ui 一样 copy-paste 3D 效果——上手成本极低，适合 Landing Page 和品牌站点的快速 3D 化，但深度定制和 GPU 内存管理需要额外注意。
原始仓库：https://github.com/MengTo/threeui
官网：https://threeui.com
npm 包：@designcodeio/threeui