基于 Node.js 本地部署 Gemini 生成的 3D 手部粒子追踪应用

完成上述准备后，即可启动本地开发服务器：

运行启动命令：

npm run dev

等待服务器启动，成功后会显示类似信息：

VITE v6.2.0 ready in 300ms ➜ Local: http://localhost:3000/ ➜ Network: http://192.168.1.100:3000/

打开浏览器，访问终端显示的本地地址（通常是 http://localhost:3000）。

步骤四：授权与使用

首次访问应用时，需要完成摄像头授权：

1. 浏览器会弹出摄像头权限请求，点击'允许'
2. 稍等片刻（首次加载需要下载 MediaPipe 模型）
3. 应用启动后会显示：
   • 全屏的 3D 粒子场景
   • 左下角的摄像头实时画面（带手部关键点标记）
   • 当你将手放在摄像头前时，粒子会跟随手部动作形成 3D 效果

注意：如果摄像头无法启动，检查：浏览器权限是否已授予、其他应用是否占用了摄像头、防火墙设置是否阻止了浏览器访问摄像头。

项目结构解析

了解项目结构有助于你更好地理解和定制应用：

particle-hand-3d/
├── components/          # React 组件
│   ├── HandParticles.tsx    # 3D 粒子效果组件
│   └── VideoOverlay.tsx     # 摄像头画面与手部标记组件
├── node_modules/        # 项目依赖
├── dist/                # 生产构建产物（构建后生成）
├── .env.local           # 环境变量（需手动创建）
├── index.html           # 入口 HTML 文件
├── App.tsx              # 应用主组件
├── package.json         # 项目配置与依赖
└── vite.config.ts       # 构建工具配置

核心功能模块：

• MediaPipe：处理手部检测与关键点识别
• Three.js：创建 3D 场景和粒子效果
• React + React Three Fiber：UI 框架与 3D 渲染集成

常见问题与解决方案

1. 应用启动后白屏
   • 检查浏览器控制台（F12）是否有错误
   • 确认 Three.js 相关依赖是否安装成功
   • 尝试清除浏览器缓存
2. 手部追踪不灵敏
   • 确保光线充足
   • 保持手部在摄像头可见范围内
   • 避免背景过于复杂
3. 端口被占用
   • 更改 vite 配置中的端口：修改 vite.config.ts 中的 server.port
   • 或终止占用端口的进程后重新启动
4. 依赖安装错误
   • 升级 Node.js 到最新稳定版
   • 尝试使用 yarn 替代 npm 安装依赖

总结

通过以上步骤，你已经成功将 Gemini 生成的 3D 手部粒子追踪应用部署到了本地计算机。这个过程涵盖了从环境准备到应用运行的完整流程，适用于大多数基于 Vite 和 React 的现代 Web 应用部署。

这类 AI 生成的应用不仅展示了大语言模型在代码生成方面的能力，也为开发者提供了快速实现创意的新思路。你可以在此基础上进一步定制粒子效果、调整交互方式，甚至结合 Gemini API 添加更智能的交互功能。