162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# 环境变量配置指南
|
||
|
||
## 概述
|
||
|
||
本项目支持通过环境变量进行灵活配置。在部署到 Vercel 时，需要正确设置这些环境变量以确保应用正常运行。
|
||
|
||
## 环境变量列表
|
||
|
||
### 必需的环境变量
|
||
|
||
| 变量名 | 描述 | 示例值 | 是否必需 |
|
||
|--------|------|--------|----------|
|
||
| `VITE_GOOGLE_API_KEY` | Google AI API 密钥 | `AIzaSy...` | 是 |
|
||
| `VITE_APP_BASE_API` | 后端API基础地址 | `https://api.example.com` | 是 |
|
||
| `VITE_STRIPE_PUBLISHABLE_KEY` | Stripe 公钥 | `pk_test_...` | 是（用于支付功能） |
|
||
|
||
### 可选的环境变量
|
||
|
||
| 变量名 | 描述 | 默认值 | 示例值 |
|
||
|--------|------|--------|--------|
|
||
| `VITE_APP_TITLE` | 应用标题 | `DeotalandAI` | `My Awesome App` |
|
||
| `VITE_APP_DESCRIPTION` | 应用描述 | `AI-Powered Creation Platform` | `Custom Description` |
|
||
| `VITE_DEV_MODE` | 开发模式 | `false` | `true` |
|
||
| `VITE_LOG_LEVEL` | 日志级别 | `error` | `debug` |
|
||
|
||
## 本地开发配置
|
||
|
||
### 1. 创建环境变量文件
|
||
|
||
在项目根目录创建 `.env.local` 文件：
|
||
|
||
```bash
|
||
# 复制示例文件
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
### 2. 填入实际配置值
|
||
|
||
编辑 `.env.local` 文件，填入你的实际配置：
|
||
|
||
```env
|
||
VITE_GOOGLE_API_KEY=你的_Google_AI_API_密钥
|
||
VITE_APP_BASE_API=https://你的API地址.com/api
|
||
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_你的_Stripe_公钥
|
||
VITE_APP_TITLE=DeotalandAI
|
||
VITE_APP_DESCRIPTION=AI-Powered Creation Platform
|
||
```
|
||
|
||
## Vercel 环境变量配置
|
||
|
||
### 方法一：Vercel Dashboard 配置
|
||
|
||
1. 登录 [Vercel Dashboard](https://vercel.com/dashboard)
|
||
2. 选择你的项目
|
||
3. 拆件 `Settings` → `Environment Variables`
|
||
4. 添加以下环境变量：
|
||
|
||
#### 生产环境变量
|
||
- `NODE_ENV` = `production`
|
||
- `VITE_GOOGLE_API_KEY` = 你的 Google API Key
|
||
- `VITE_APP_BASE_API` = 你的生产环境 API 地址
|
||
- `VITE_STRIPE_PUBLISHABLE_KEY` = 你的 Stripe 公钥
|
||
|
||
#### 预览环境变量
|
||
- `NODE_ENV` = `production`
|
||
- `VITE_GOOGLE_API_KEY` = 你的 Google API Key
|
||
- `VITE_APP_BASE_API` = 你的预览环境 API 地址
|
||
- `VITE_STRIPE_PUBLISHABLE_KEY` = 你的 Stripe 公钥
|
||
|
||
#### 开发环境变量
|
||
- `NODE_ENV` = `development`
|
||
- `VITE_GOOGLE_API_KEY` = 你的 Google API Key
|
||
- `VITE_APP_BASE_API` = 你的本地或开发环境 API 地址
|
||
|
||
### 方法二：通过 Vercel CLI 配置
|
||
|
||
```bash
|
||
# 安装 Vercel CLI
|
||
npm i -g vercel
|
||
|
||
# 登录 Vercel
|
||
vercel login
|
||
|
||
# 设置环境变量
|
||
vercel env add VITE_GOOGLE_API_KEY production
|
||
vercel env add VITE_APP_BASE_API production
|
||
vercel env add VITE_STRIPE_PUBLISHABLE_KEY production
|
||
|
||
# 部署项目
|
||
vercel --prod
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
### 1. API Key 安全
|
||
- **永远不要**在前端代码中硬编码 API Key
|
||
- 使用环境变量存储敏感信息
|
||
- 定期轮换 API Key
|
||
- 为不同环境使用不同的 API Key
|
||
|
||
### 2. Stripe 配置
|
||
- 生产环境使用 `pk_live_` 开头的密钥
|
||
- 开发/测试环境使用 `pk_test_` 开头的密钥
|
||
- 永远不要在前端暴露 Stripe Secret Key
|
||
|
||
### 3. CORS 配置
|
||
确保你的后端 API 正确配置了 CORS，允许来自 Vercel 域名的请求：
|
||
|
||
```javascript
|
||
// 后端 CORS 配置示例
|
||
app.use(cors({
|
||
origin: [
|
||
'http://localhost:3000',
|
||
'https://your-app.vercel.app',
|
||
'https://your-custom-domain.com'
|
||
],
|
||
credentials: true
|
||
}));
|
||
```
|
||
|
||
## 验证配置
|
||
|
||
部署完成后，你可以通过以下方式验证环境变量是否正确配置：
|
||
|
||
### 1. 浏览器开发者工具
|
||
打开浏览器开发者工具，查看 Network 标签页，确认 API 请求是否正常发送。
|
||
|
||
### 2. 应用日志
|
||
在 Vercel Dashboard 中查看 Function Logs，确认是否有环境变量相关的错误。
|
||
|
||
### 3. 简单测试
|
||
在浏览器控制台中运行：
|
||
|
||
```javascript
|
||
// 检查环境变量是否正确加载
|
||
console.log('Google API Key:', import.meta.env.VITE_GOOGLE_API_KEY ? '已配置' : '未配置');
|
||
console.log('API Base URL:', import.meta.env.VITE_APP_BASE_API || '未配置');
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 环境变量未生效？
|
||
A:
|
||
1. 检查变量名是否以 `VITE_` 开头
|
||
2. 重新部署应用
|
||
3. 清除浏览器缓存
|
||
|
||
### Q: API 请求失败？
|
||
A:
|
||
1. 检查 `VITE_APP_BASE_API` 是否正确
|
||
2. 确认后端服务正常运行
|
||
3. 检查 CORS 配置
|
||
|
||
### Q: Stripe 支付不工作？
|
||
A:
|
||
1. 确认使用了正确的 Stripe 公钥
|
||
2. 检查 Stripe 账户状态
|
||
3. 确认 Stripe 公钥与当前环境匹配
|
||
|
||
## 更新日志
|
||
|
||
- 2025-01-13: 初始版本创建 |