# 前端环境变量配置说明

## 快速开始

### 1. 复制环境配置文件

```bash
cd frontend
cp .env.example .env
```

### 2. 编辑 `.env` 文件

根据需要修改配置项，最重要的是 `VITE_ENABLE_HTTPS` 开关。

## 配置项列表

| 配置项 | 说明 | 默认值 | 必需 |
|--------|------|--------|------|
| `VITE_ENABLE_HTTPS` | HTTPS 开关（`true`/`false`） | `true` | 是 |
| `VITE_SSL_KEYFILE` | SSL 私钥路径 | `../ssl/key.pem` | 否 |
| `VITE_SSL_CERTFILE` | SSL 证书路径 | `../ssl/cert.pem` | 否 |
| `VITE_WS_URL` | WebSocket URL | `wss://localhost:8000/ws` | 否 |
| `VITE_API_BASE_URL` | API 基础 URL | - | 否 |
| `VITE_API_CLIENT_KEY` | API Key，用于验证请求来源（必须与后端 `API_CLIENT_KEY` 一致） | - | 是 |
| `VITE_APP_BASE_PATH` | 前端部署子路径（以 `/` 开头和结尾） | `/` | 否 |
| `VITE_WELCOME_VIDEO_URL` | Welcome 页面视频 URL | `https://www.lyrria.com/img/Lyrria-video.mp4` | 否 |
| `VITE_OSS_BASE_URL` | OSS 资源基础 URL（用于图片、GIF 等静态资源） | `https://www.lyrria.com/img` | 否 |

## 使用场景

### 场景 1: 开发环境（推荐 HTTPS）

```bash
# .env
VITE_ENABLE_HTTPS=true
VITE_SSL_KEYFILE=
VITE_SSL_CERTFILE=
VITE_WS_URL=wss://localhost:8000/ws
```

**说明**：使用自签名证书，支持麦克风访问。首次访问需要浏览器信任证书。

### 场景 2: 局域网测试（HTTP）

```bash
# .env
VITE_ENABLE_HTTPS=false
VITE_WS_URL=ws://192.168.2.112:8000/ws
```

**说明**：关闭 HTTPS，使用 HTTP 访问。**注意**：浏览器可能限制麦克风权限。

### 场景 3: 生产环境（Nginx 托管）

```bash
# .env.production
VITE_ENABLE_HTTPS=false
VITE_WS_URL=wss://www.hikelly.chat/ws
# 将应用部署在子路径 /chatbot/ 时需要设置：
# VITE_APP_BASE_PATH=/chatbot/
```

**说明**：前端使用 HTTP，由 Nginx 统一处理 HTTPS。

### 场景 4: 自定义证书路径

```bash
# .env
VITE_ENABLE_HTTPS=true
VITE_SSL_KEYFILE=/path/to/custom/key.pem
VITE_SSL_CERTFILE=/path/to/custom/cert.pem
VITE_WS_URL=wss://localhost:8000/ws
```

**说明**：使用自定义证书路径。

## 启动模式检测

启动开发服务器时，终端会显示当前模式：

### HTTPS 启用成功

```
✅ HTTPS已启用，使用SSL证书:
  证书: /path/to/cert.pem
  私钥: /path/to/key.pem
```

### HTTPS 启用但证书缺失

```
⚠️  HTTPS已启用但SSL证书不存在，以HTTP模式启动
  证书路径: /path/to/cert.pem
  私钥路径: /path/to/key.pem
```

### HTTPS 已禁用

```
ℹ️  HTTPS已禁用（VITE_ENABLE_HTTPS=false），以HTTP模式启动
```

## 常见问题

### Q1: 如何切换到 HTTP 模式？

编辑 `.env` 文件，设置：
```bash
VITE_ENABLE_HTTPS=false
```

### Q2: HTTPS 模式下浏览器提示不安全？

这是因为使用了自签名证书。点击"继续访问"或在浏览器中信任该证书。

### Q3: 为什么推荐开发环境使用 HTTPS？

现代浏览器（Chrome/Firefox/Safari）要求 HTTPS 才能访问麦克风等敏感权限。

### Q4: 生产环境需要配置证书吗？

不需要。生产环境建议使用 Nginx 托管，由 Nginx 统一管理证书。前端设置 `VITE_ENABLE_HTTPS=false`。

## 更新日志

- **2025-11-05**: 新增 `VITE_ENABLE_HTTPS` 开关，支持动态控制 HTTPS