liushuyang
/
crush-level-web
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
crush-level-web/docs/EnvironmentVariables.md

4.4 KiB
Raw Blame History

环境变量配置说明

概述

本文档说明项目所需的环境变量配置。请在项目根目录创建 .env.local 文件并添加以下配置。

必需的环境变量

应用配置

# 应用的基础 URL
# 开发环境: http://localhost:3000
# 生产环境: https://test.crushlevel.ai 或您的域名
NEXT_PUBLIC_APP_URL=https://test.crushlevel.ai

Discord OAuth 配置

# 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
  2. 创建或选择应用
  3. 在 OAuth2 设置中配置回调 URL：
    • https://test.crushlevel.ai/api/auth/discord/callback
    • http://localhost:3000/api/auth/discord/callback (开发环境)
  4. 复制 Client ID

Google OAuth 配置

# 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
  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 文件：

# .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)

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)

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_ 前缀的变量会暴露到浏览器
    • 敏感的服务端密钥不要使用此前缀

验证配置

检查环境变量是否正确加载

在组件中添加调试代码（仅开发环境）：

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. 添加环境变量

相关文档