QUICKSTART.md 3.8 KB
Tolan 前端快速启动指南
📋 前置要求
- Node.js >= 18.0.0
- npm >= 9.0.0
- 后端服务已启动（
backend/目录）
🚀 快速启动
1. 安装依赖
cd /Users/wuzilong/work/00code/Tolan/frontend
npm install
2. 配置环境变量（可选）
创建 .env.local 文件：
# 如果后端在本地运行
VITE_WS_URL=ws://localhost:8000/ws/realtime
# 如果后端使用HTTPS
VITE_WS_URL=wss://localhost:8443/ws/realtime
如果不配置，默认使用 ws://localhost:8000/ws/realtime
3. 启动开发服务器
npm run dev
应用将在 http://localhost:5173 启动
4. 在浏览器中打开
📱 使用步骤
等待初始化
- 页面加载时会自动连接WebSocket服务器
- 初始化录音器和播放器
- 看到"连接成功"提示
开始对话
- 按住录音按钮开始说话
- 动画IP会切换到"倾听"状态
- 说完后松开按钮
接收回复
- AI处理语音并返回音频
- 动画IP切换到"说话"状态
- 自动播放AI回复
继续对话
- 播放完成后，动画IP回到"待机"状态
- 可以再次按住按钮继续对话
🔧 故障排查
问题1: 连接失败
症状: 显示"连接中..."但一直无法连接
解决方案:
- 确认后端服务已启动
- 检查WebSocket URL配置
- 查看浏览器控制台错误信息
# 检查后端是否运行
curl http://localhost:8000/docs
问题2: 麦克风权限被拒绝
症状: 点击录音按钮没有反应
解决方案:
- 浏览器会弹出权限请求，点击"允许"
- 如果已拒绝，在浏览器设置中重新授权
- 确保使用HTTPS或localhost
问题3: 无法播放音频
症状: 收到回复但没有声音
解决方案:
- 检查浏览器是否静音
- 检查系统音量设置
- 确认浏览器支持OGG/Opus格式
- 查看控制台是否有错误
问题4: 延迟过高
症状: 响应时间超过1秒
解决方案:
- 检查网络连接
- 确认后端连接池已启动
- 查看控制台中显示的延迟数据
- 检查后端日志
📊 性能监控
应用会在控制台输出性能指标：
端到端延迟: 285ms
收到音频数据: 2048 bytes
音频播放状态: playing
目标延迟: < 300ms
🌐 浏览器兼容性
推荐浏览器
- ✅ Chrome 90+（最佳体验）
- ✅ Edge 90+
- ✅ Safari 14+
- ✅ Firefox 88+
移动端
- ✅ iOS Safari 14+
- ✅ Android Chrome 90+
已知问题
- iOS需要在用户交互中激活录音
- 某些Android浏览器不支持所有音频参数
🛠 开发命令
# 安装依赖
npm install
# 启动开发服务器（热更新）
npm run dev
# 生产构建
npm run build
# 预览生产构建
npm run preview
# 代码检查
npm run lint
📂 项目结构
frontend/
├── src/
│ ├── components/ # React组件
│ ├── stores/ # 状态管理
│ ├── utils/ # 工具模块
│ ├── config.ts # 配置
│ └── main.tsx # 入口
├── public/ # 静态资源
└── package.json
🔗 相关文档
💡 提示
- 首次使用: 浏览器会请求麦克风权限，务必允许
- iOS设备: 首次点击需要激活音频上下文
- 网络环境: 建议在良好的网络环境下使用
- HTTPS: 生产环境必须使用HTTPS
📞 获取帮助
遇到问题？
- 查看浏览器控制台（F12）的错误信息
- 检查后端日志
- 参考完整文档
- 查看GitHub Issues
祝您使用愉快！🎉