Vibe Coder
環境變數與 Secret 管理：本機、測試、正式三套環境不搞混
現代專案要區分本機、測試、正式三套環境，各自用不同的資料庫和 API Key，最危險的錯誤是在本機用正式環境的資料庫或金流 Key。.env 不能 commit 到 Git，要用 .env.example 當範本；Next.js 和 Vite 裡，只有 NEXT_PUBLIC_ 或 VITE_ 前綴的變數才能公開，API Key 絕對不能加這個前綴。
環境變數與 Secret 管理：本機、測試、正式三套環境不搞混
本機開發時如果不小心用了正式環境的 Stripe Key，一個 bug 就可能對真實使用者扣款；本機連到正式資料庫，測試資料搞亂了真實使用者的資料，後果同樣嚴重。AI 生成的程式通常只有一個 .env，沒有多環境的概念，所有環境共用同一套設定，需要你主動建立正確的結構。這篇帶你把本機、測試、正式三套環境的設定徹底分開。
你將學到什麼
三個標準環境
development、staging、production，各自的用途、資料庫與 API Key。
.env 檔案家族
.env、.env.local、.env.example，哪些能 commit、哪些絕對不行。
框架的讀取陷阱
Next.js 和 Vite 的公開前綴，一不小心就把 Key 暴露在瀏覽器裡。
進階集中管理
用 Doppler 取代多份 .env，團隊不用再互傳設定檔。
三個標準環境
| 環境 | 英文 | 用途 | 資料庫 | API Key |
|---|---|---|---|---|
| 本機開發 | development | 你自己開發和測試 | 本機 DB 或測試 DB | Sandbox／Test Key |
| 測試環境 | staging | 上線前驗收 | 獨立測試 DB | Sandbox／Test Key |
| 正式環境 | production | 真實使用者使用 | 正式 DB | 正式 Key |
最危險的錯誤在本機開發時用正式環境的資料庫連線字串或正式 Stripe Key。任何 bug 都會直接影響真實使用者和真實金流。測試環境一定要用 Sandbox Key 和測試 DB。
.env 檔案的家族成員
現代專案通常有多個 .env 相關檔案，各有不同用途。
| 檔案名稱 | 用途 | 要 commit 嗎 |
|---|---|---|
| .env | 本機開發用的實際設定值 | 不要，加進 .gitignore |
| .env.local | 覆蓋 .env 的本機個人設定（優先級更高） | 不要 |
| .env.example | 範本，說明需要哪些變數（值用假的） | 要 commit |
| .env.production | 正式環境設定（通常交給平台環境變數管理） | 不要 |
| .env.test | 跑測試時用的設定 | 視情況，值用假的可以 commit |
# 複製這個檔案為 .env 並填入真實值
# 不要在這裡填入真實的 Key！
OPENAI_API_KEY=sk-your-key-here
DATABASE_URL=postgresql://user:pass@localhost/dbname
STRIPE_SECRET_KEY=sk_test_your-key-here
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co.env.example 是給團隊成員的說明書新成員加入專案，clone repo 後第一件事是複製 .env.example 成 .env，然後填入自己的 Key。這樣他知道需要哪些設定，也不會 commit 真實的 Key。
各框架的環境變數讀取方式
| 框架 | 讀取方式 | 前端可見前綴 |
|---|---|---|
| Python（FastAPI／Flask） | os.getenv("KEY") 加 python-dotenv | 無（後端只） |
| Next.js | process.env.KEY | NEXT_PUBLIC_ 開頭才能在瀏覽器讀到 |
| Vite（React） | import.meta.env.VITE_KEY | VITE_ 開頭才能在瀏覽器讀到 |
| Node.js | process.env.KEY 加 dotenv | 無（後端只） |
前端框架的安全陷阱Next.js 和 Vite 裡，只有特定前綴（NEXT_PUBLIC_ 或 VITE_）的環境變數才會打包進前端程式碼。API Key 絕對不能有這個前綴，否則你的 Key 會暴露在所有使用者的瀏覽器裡。只有可以公開的設定（如 Supabase URL）才加這個前綴。
多環境設定的最佳實踐
- 本機用 .env，絕對不 commit。把 .env 加進 .gitignore，用 .env.example 記錄需要哪些變數。
- 正式環境用平台的環境變數設定。Vercel、Railway 都有介面讓你填入 Key，不透過 .env 檔案。
- Stripe 等金流一定要用 Sandbox Key 開發。Stripe 提供測試用的 sk_test_ 開頭 Key，開發時只能用這個。
- 資料庫用不同的連線字串。本機開發用本機 DB，正式環境用雲端 DB，連線字串完全分開。
進階：用 Doppler 集中管理多環境
當專案複雜度增加，例如多個服務、多個環境、多個成員，用 Doppler 集中管理比維護多個 .env 檔案更有效率。
| 概念 | 說明 |
|---|---|
| Project | 一個應用程式，例如「my-app」 |
| Config | 一個環境的設定，例如 dev、staging、prd |
| Secret | 一個環境變數，例如 OPENAI_API_KEY |
# 安裝 CLI
brew install dopplerhq/cli/doppler # Mac
# 登入並設定專案
doppler login
doppler setup
# 用 Doppler 的 secret 執行程式（不需要 .env）
doppler run -- python3 app.py
doppler run -- uvicorn app:app
# 查看目前環境的所有 secret
doppler secrets常見問答
.env 和 .env.example 有什麼不同？
.env 存放本機開發用的實際設定值，包含真實 Key，絕對不能 commit，要加進 .gitignore。.env.example 是範本，用假的佔位值說明需要哪些變數，可以放心 commit，讓新成員知道需要設定什麼。
為什麼 API Key 不能加 NEXT_PUBLIC_ 前綴？
Next.js 只有 NEXT_PUBLIC_ 開頭的環境變數才會被打包進前端程式碼，讓瀏覽器讀到。如果 API Key 加了這個前綴，所有使用者都能在瀏覽器裡直接看到你的 Key，等於公開金鑰。Vite 的 VITE_ 前綴也是同樣的風險。
開發 Stripe 等金流功能要注意什麼？
開發時一定要用 Stripe 提供的 sk_test_ 開頭 Sandbox Key，不能用正式 Key。本機的 bug 如果連到正式金流，就可能對真實使用者造成扣款等嚴重後果。
Doppler 這類工具解決了什麼問題？
團隊成員原本需要互相傳送 .env 檔案，這本身就是安全風險。用 Doppler 之後，每個人執行 doppler setup 就能取得對應環境的 Secret，更新 Secret 時所有人同步拿到新值，不用手動改檔案。