dramaling-vocab-learning/docs/03_development/setup/env-setup.md

環境變數設置指南

📋 前置準備

在開始之前，請確保你已經：

1. 複製 .env.example 為 .env.local
2. 註冊所需的服務帳號

cp .env.example .env.local

🔑 環境變數詳細說明

1. Supabase 設置

步驟 1: 建立 Supabase 專案

1. 前往 Supabase Dashboard
2. 點擊「New Project」
3. 設定專案名稱：dramaling-dev
4. 設定資料庫密碼（請妥善保存）
5. 選擇地區：Southeast Asia (Singapore)

步驟 2: 取得 API 金鑰

1. 進入專案 → Settings → API
2. 複製以下資訊到 .env.local：

   NEXT_PUBLIC_SUPABASE_URL=https://[YOUR-PROJECT-REF].supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=[anon public key]
   SUPABASE_SERVICE_ROLE_KEY=[service_role key]
   

步驟 3: 取得資料庫連線字串

1. Settings → Database
2. 複製 Connection string (URI)：

   DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres
   

2. Google Gemini API 設置

步驟 1: 啟用 Gemini API

1. 前往 Google AI Studio
2. 點擊「Get API Key」
3. 選擇或建立 Google Cloud 專案
4. 複製 API Key

步驟 2: 設定環境變數

GOOGLE_GEMINI_API_KEY=your_api_key_here

3. NextAuth 設置

步驟 1: 生成 Secret

在終端執行：

openssl rand -base64 32

步驟 2: 設定環境變數

NEXTAUTH_URL=http://localhost:3000  # 開發環境
NEXTAUTH_SECRET=[生成的隨機字串]

生產環境：將 NEXTAUTH_URL 改為實際網域

4. Google OAuth 設置（選用）

步驟 1: 建立 OAuth 2.0 憑證

1. 前往 Google Cloud Console
2. 選擇專案 → APIs & Services → Credentials
3. Create Credentials → OAuth 2.0 Client ID
4. 應用程式類型：Web application
5. 授權重新導向 URI：
   • 開發：http://localhost:3000/api/auth/callback/google
   • 生產：https://your-domain.com/api/auth/callback/google

步驟 2: 設定環境變數

GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret

🔒 安全性注意事項

重要提醒

1. 絕對不要 將 .env.local 提交到 Git
2. 確保 .gitignore 包含 .env.local
3. 定期輪換 API 金鑰和密碼
4. 使用不同的金鑰 給開發和生產環境

驗證 .gitignore

確認以下內容在 .gitignore 中：

# 環境變數
.env
.env.local
.env.production.local
.env.development.local
.env.test.local

✅ 環境變數檢查清單

執行以下命令驗證設置：

# 檢查環境變數是否載入
npm run dev

# 測試 Supabase 連線
npx supabase status

# 驗證所有必要變數
node -e "
const required = [
  'NEXT_PUBLIC_SUPABASE_URL',
  'NEXT_PUBLIC_SUPABASE_ANON_KEY',
  'GOOGLE_GEMINI_API_KEY',
  'NEXTAUTH_SECRET'
];
const missing = required.filter(key => !process.env[key]);
if (missing.length) {
  console.error('Missing:', missing);
  process.exit(1);
} else {
  console.log('✅ All required env vars are set');
}
"

🚀 Vercel 部署設置

當準備部署時：

1. 前往 Vercel Dashboard → Project Settings → Environment Variables
2. 逐一添加所有環境變數
3. 設定不同環境的變數：
   • Production：生產環境
   • Preview：預覽環境
   • Development：開發環境

📝 範例完整 .env.local

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xyzcompany.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Gemini
GOOGLE_GEMINI_API_KEY=AIzaSyD-xxxxxxxxxxxxxxxxxxxx

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=pV2wPbAaHgYq6qBhNwzSL1HdMv8XHkZ3kPmR7hFwQx4=

# Google OAuth
GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxx

# Database
DATABASE_URL=postgresql://postgres:yourpassword@db.xyzcompany.supabase.co:5432/postgres

# Environment
NODE_ENV=development

🆘 常見問題

Q: NEXT_PUBLIC_ 前綴的用途？

A: Next.js 中，只有 NEXT_PUBLIC_ 開頭的變數會暴露給瀏覽器端。

Q: 如何在不同環境使用不同設定？

A: 使用 .env.development 和 .env.production 分別設定。

Q: Supabase 連線失敗？

A: 檢查防火牆設定，確認 IP 沒有被限制（Supabase Dashboard → Settings → Database → Allowed IPs）。

Q: API Key 洩露了怎麼辦？

A: 立即到對應服務的控制台重新生成新的金鑰。