174 lines
4.4 KiB
Markdown
174 lines
4.4 KiB
Markdown
|
# 环境变量配置说明
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
本文档说明项目所需的环境变量配置。请在项目根目录创建 `.env.local` 文件并添加以下配置。
|
|||
|
|
|
|||
|
|
## 必需的环境变量
|
|||
|
|
|
|||
|
|
### 应用配置
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 应用的基础 URL
|
|||
|
|
# 开发环境: http://localhost:3000
|
|||
|
|
# 生产环境: https://test.crushlevel.ai 或您的域名
|
|||
|
|
NEXT_PUBLIC_APP_URL=https://test.crushlevel.ai
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Discord OAuth 配置
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Discord OAuth 客户端 ID
|
|||
|
|
# 从 Discord Developer Portal 获取
|
|||
|
|
# https://discord.com/developers/applications
|
|||
|
|
NEXT_PUBLIC_DISCORD_CLIENT_ID=your_discord_client_id_here
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**获取步骤**:
|
|||
|
|
1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
|
|||
|
|
2. 创建或选择应用
|
|||
|
|
3. 在 OAuth2 设置中配置回调 URL：
|
|||
|
|
- `https://test.crushlevel.ai/api/auth/discord/callback`
|
|||
|
|
- `http://localhost:3000/api/auth/discord/callback` (开发环境)
|
|||
|
|
4. 复制 Client ID
|
|||
|
|
|
|||
|
|
### Google OAuth 配置
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Google OAuth 客户端 ID
|
|||
|
|
# 从 Google Cloud Console 获取
|
|||
|
|
# https://console.cloud.google.com/
|
|||
|
|
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id_here
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**获取步骤**:
|
|||
|
|
1. 访问 [Google Cloud Console](https://console.cloud.google.com/)
|
|||
|
|
2. 创建或选择项目
|
|||
|
|
3. 启用 Google+ API
|
|||
|
|
4. 创建 OAuth 2.0 客户端 ID
|
|||
|
|
5. 配置授权重定向 URI：
|
|||
|
|
- `https://test.crushlevel.ai/api/auth/google/callback`
|
|||
|
|
- `http://localhost:3000/api/auth/google/callback` (开发环境)
|
|||
|
|
6. 复制客户端 ID
|
|||
|
|
|
|||
|
|
## 环境变量文件示例
|
|||
|
|
|
|||
|
|
创建 `.env.local` 文件：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# .env.local
|
|||
|
|
|
|||
|
|
# App Configuration
|
|||
|
|
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
|||
|
|
|
|||
|
|
# Discord OAuth
|
|||
|
|
NEXT_PUBLIC_DISCORD_CLIENT_ID=1234567890123456789
|
|||
|
|
|
|||
|
|
# Google OAuth
|
|||
|
|
NEXT_PUBLIC_GOOGLE_CLIENT_ID=1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 不同环境的配置
|
|||
|
|
|
|||
|
|
### 开发环境 (`.env.local`)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
|||
|
|
NEXT_PUBLIC_DISCORD_CLIENT_ID=dev_discord_client_id
|
|||
|
|
NEXT_PUBLIC_GOOGLE_CLIENT_ID=dev_google_client_id
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 生产环境 (`.env.production`)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
NEXT_PUBLIC_APP_URL=https://test.crushlevel.ai
|
|||
|
|
NEXT_PUBLIC_DISCORD_CLIENT_ID=prod_discord_client_id
|
|||
|
|
NEXT_PUBLIC_GOOGLE_CLIENT_ID=prod_google_client_id
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 安全注意事项
|
|||
|
|
|
|||
|
|
### ⚠️ 重要提醒
|
|||
|
|
|
|||
|
|
1. **不要提交敏感信息到 Git**
|
|||
|
|
- `.env.local` 已在 `.gitignore` 中
|
|||
|
|
- 不要将真实的密钥提交到代码库
|
|||
|
|
|
|||
|
|
2. **使用不同的凭据**
|
|||
|
|
- 开发环境和生产环境使用不同的 OAuth 凭据
|
|||
|
|
- 定期轮换生产环境的密钥
|
|||
|
|
|
|||
|
|
3. **限制回调 URL**
|
|||
|
|
- 只添加必要的回调 URL
|
|||
|
|
- 不要使用通配符
|
|||
|
|
|
|||
|
|
4. **环境变量前缀**
|
|||
|
|
- `NEXT_PUBLIC_` 前缀的变量会暴露到浏览器
|
|||
|
|
- 敏感的服务端密钥不要使用此前缀
|
|||
|
|
|
|||
|
|
## 验证配置
|
|||
|
|
|
|||
|
|
### 检查环境变量是否正确加载
|
|||
|
|
|
|||
|
|
在组件中添加调试代码（仅开发环境）：
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
console.log('App URL:', process.env.NEXT_PUBLIC_APP_URL)
|
|||
|
|
console.log('Discord Client ID:', process.env.NEXT_PUBLIC_DISCORD_CLIENT_ID)
|
|||
|
|
console.log('Google Client ID:', process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 常见问题
|
|||
|
|
|
|||
|
|
**问题 1**: 环境变量未生效
|
|||
|
|
|
|||
|
|
**解决方案**:
|
|||
|
|
- 重启开发服务器 (`npm run dev`)
|
|||
|
|
- 确保文件名正确 (`.env.local`)
|
|||
|
|
- 检查变量名拼写
|
|||
|
|
|
|||
|
|
**问题 2**: OAuth 回调失败
|
|||
|
|
|
|||
|
|
**解决方案**:
|
|||
|
|
- 检查 `NEXT_PUBLIC_APP_URL` 是否正确
|
|||
|
|
- 确保回调 URL 在 OAuth 提供商处正确配置
|
|||
|
|
- 开发环境使用 `http://localhost:3000`，生产环境使用实际域名
|
|||
|
|
|
|||
|
|
**问题 3**: 客户端 ID 无效
|
|||
|
|
|
|||
|
|
**解决方案**:
|
|||
|
|
- 确认复制的是 Client ID 而不是 Client Secret
|
|||
|
|
- 检查是否有多余的空格或换行符
|
|||
|
|
- 确认 OAuth 应用状态为已发布/激活
|
|||
|
|
|
|||
|
|
## 添加新的环境变量
|
|||
|
|
|
|||
|
|
当添加新的环境变量时：
|
|||
|
|
|
|||
|
|
1. 在 `.env.local` 中添加变量
|
|||
|
|
2. 更新本文档
|
|||
|
|
3. 通知团队成员更新他们的本地配置
|
|||
|
|
4. 在部署平台（Vercel/Netlify 等）配置生产环境变量
|
|||
|
|
|
|||
|
|
## 部署平台配置
|
|||
|
|
|
|||
|
|
### Vercel
|
|||
|
|
|
|||
|
|
1. 进入项目设置
|
|||
|
|
2. 选择 "Environment Variables"
|
|||
|
|
3. 添加所有 `NEXT_PUBLIC_*` 变量
|
|||
|
|
4. 为不同环境（Production/Preview/Development）设置不同的值
|
|||
|
|
|
|||
|
|
### Netlify
|
|||
|
|
|
|||
|
|
1. 进入 Site settings
|
|||
|
|
2. 选择 "Build & deploy" > "Environment"
|
|||
|
|
3. 添加环境变量
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
|
|||
|
|
- [Next.js 环境变量文档](https://nextjs.org/docs/app/building-your-application/configuring/environment-variables)
|
|||
|
|
- [Discord OAuth 文档](https://discord.com/developers/docs/topics/oauth2)
|
|||
|
|
- [Google OAuth 文档](https://developers.google.com/identity/protocols/oauth2)
|
|||
|
|
|