Tolan/frontend/ENV_CONFIG.md

前端环境变量配置说明

配置文件

在 frontend/ 目录下创建 .env 文件：

# 复制示例配置
cp .env.example .env

# 或手动创建
touch .env

配置选项

方式1：分别配置主机和端口（推荐）

VITE_BACKEND_HOST=localhost
VITE_BACKEND_PORT=8000

方式2：使用IP地址（局域网访问）

VITE_BACKEND_HOST=192.168.2.105
VITE_BACKEND_PORT=8000

方式3：直接指定完整URL（最灵活）

# HTTP
VITE_WS_URL=ws://192.168.2.105:8000/ws/realtime

# HTTPS
VITE_WS_URL=wss://192.168.2.105:8000/ws/realtime

使用场景

本地开发

VITE_BACKEND_HOST=localhost
VITE_BACKEND_PORT=8000

访问：http://localhost:5173

手机访问电脑服务（同一局域网）

1. 查看电脑IP地址：

   • Mac: 系统设置 → 网络 → Wi-Fi → 详细信息 查看IP
   • Windows: 命令行运行 ipconfig
   • Linux: 命令行运行 ifconfig 或 ip addr

2. 修改 .env 配置：

   VITE_BACKEND_HOST=192.168.2.105  # 替换为你的电脑IP
   VITE_BACKEND_PORT=8000
   

   1. 重启前端服务： bash npm run dev

3. 手机浏览器访问：

   http://192.168.2.105:5173
   

HTTPS访问

如果需要HTTPS（用于PWA、麦克风权限等）：

VITE_WS_URL=wss://192.168.2.105:8000/ws/realtime

注意：需要后端配置SSL证书

自动协议检测

前端会自动根据页面协议选择WebSocket协议：

• 访问 http://... → 使用 ws://
• 访问 https://... → 使用 wss://

完整示例

示例1：开发环境（localhost）

.env：

VITE_BACKEND_HOST=localhost
VITE_BACKEND_PORT=8000

示例2：局域网IP访问

.env：

VITE_BACKEND_HOST=192.168.2.105
VITE_BACKEND_PORT=8000

示例3：生产环境（域名+HTTPS）

.env：

VITE_WS_URL=wss://api.yourdomain.com/ws/realtime

验证配置

启动前端后，在浏览器控制台查看：

开始初始化应用...
连接WebSocket: ws://192.168.2.105:8000/ws/realtime

确认URL正确即可。

故障排查

连接失败

1. 检查后端是否启动：

   curl http://192.168.2.105:8000/docs
   

   1. 检查防火墙：
   2. Mac: 系统设置 → 网络 → 防火墙

   3. Windows: 控制面板 → Windows Defender 防火墙

   4. 检查后端CORS配置： 确保 backend/config.py 包含你的IP：

      CORS_ORIGINS: list = [
      "http://localhost:5173",
      "http://192.168.2.105:5173",  # 添加你的IP
      ]
      

修改后需要

1. 重启前端服务：npm run dev
2. 清除浏览器缓存
3. 刷新页面