前端环境变量配置说明

快速开始

1. 复制环境配置文件

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）

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

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

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

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

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

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

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

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

场景 4: 自定义证书路径

# .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 文件，设置：

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

ENV_CONFIG.md 3.3 KB Vēsture Neapstrādāts