Python-dotenv 環境變數管理

在開發實務專案（尤其是後端、API 或爬蟲）時，我們經常需要處理一些敏感資訊，例如資料庫密碼、API 金鑰（API Key）或是第三方服務的憑證。絕對不要將這些資訊直接寫死 (Hardcode) 在程式碼中。

常見的做法是將這些設定存在「環境變數」中。Python-dotenv 是一個輕量級工具，它能讓你將這些設定寫在一個名為 .env 的檔案裡，並在程式啟動時自動載入，讓你的程式碼既安全又具備高度的可配置性。

為什麼要使用 .env 檔案？

1. 安全性：敏感資料與代碼分離。只要將 .env 加入 .gitignore，機密就不會洩漏到 GitHub 等版本控制平台。
2. 靈活性：輕鬆在不同的環境（開發環境、測試環境、預發行環境、正式環境）之間切換配置，而不需要修改任何一行程式碼。
3. 遵循標準：這是 12-Factor App 原則中「將配置存於環境中」的最佳實踐。

安裝

pip install python-dotenv

基礎工作流程

步驟 1：建立 .env 檔案

在專案的根目錄建立一個名為 .env 的檔案（注意開頭有一個點），並以 KEY=VALUE 的格式撰寫：

# 資料庫連線設定
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASS=very_secret_password

# 第三方 API 金鑰
OPENAI_API_KEY=sk-xxxx...
STRIPE_SECRET=sk_test_...

# 開發標記
DEBUG=True

步驟 2：在 Python 中載入與讀取

使用 load_dotenv() 函式將 .env 中的變數載入到系統環境變數中，隨後透過 Python 內建的 os 模組讀取。

import os
from dotenv import load_dotenv

# 1. 啟動時立即載入 (會尋找當前目錄下的 .env)
load_dotenv()

# 2. 像讀取系統環境變數一樣讀取它們
db_host = os.getenv("DB_HOST")
debug_mode = os.getenv("DEBUG") == "True" # 注意：讀出來的值永遠是字串

# 3. 提供預設值 (若環境變數中找不到該項目)
api_endpoint = os.getenv("API_URL", "https://api.default.com")

print(f"資料庫連結位置: {db_host}")

進階應用技巧

1. 變數擴充 (Variable Expansion)

你可以引用檔案中已定義的變數，減少重複輸入。

BASE_URL=https://api.myapp.com
AUTH_URL=${BASE_URL}/v1/auth
DATA_URL=${BASE_URL}/v1/data

2. 指定特定的 .env 路徑

如果你的檔案不在啟動腳本所在的目錄，或者你想根據環境載入不同的檔案：

from pathlib import Path
from dotenv import load_dotenv

env_path = Path('.') / 'configs' / '.env.production'
load_dotenv(dotenv_path=env_path, override=True)
# override=True 代表若系統變數已存在同名項目，以 .env 檔案為準

3. 搭配 Pydantic 使用 (專業推薦)

如果你正在開發 FastAPI 或是較具規模的服務，強烈建議整合 Pydantic Settings。它能提供「型別驗證」與「自動分選」。

# 安裝: pip install pydantic-settings
from pydantic_settings import BaseSettings, SettingsConfigDict

class GlobalConfig(BaseSettings):
    # 自動將環境變數轉為對應型別
    db_port: int = 5432
    db_host: str
    openai_api_key: str

    # 設定讀取的路徑
    model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8')

settings = GlobalConfig()
print(settings.db_port) # 輸出為 int 型別

重要的安全實踐

2. 提供 .env.example 為了讓協作者知道專案需要哪些設定，你應該 commit 一個範本檔。

.env.example 內容：

DB_HOST=
DB_USER=
DB_PASS=

總結

• 機密資料隔離是開發者的基本素養。
• 專案入口點的第一行通常就是 load_dotenv()。
• 透過 os.getenv 獲取配置，或透過 Pydantic 進行強型別管理。
• 養成建立 .env.example 的好習慣，方便團隊開發與部署測試。