概要

在 Python 應用中，為了將配置信息與代碼分離、增強安全性并支持多環境（開發、測試、生產）運行，使用專門的模塊來管理環境變量是最佳實踐。常見工具包括：

• 標準庫 os.environ：直接讀取操作系統環境變量，適合簡單場景；

• python-dotenv：從 .env 文件加載變量到 os.environ，符合十二要素應用 (PyPI)；

• python-decouple：更嚴格地將配置與代碼分離，支持類型轉換、INI 和 .env 雙格式文件 (PyPI)；

• environs：簡化變量解析與驗證，支持多種類型、變量前綴、.env 文件和框架集成 (PyPI)；

• django-environ：面向 Django 項目，解析數據庫 URL 等特殊變量并填充 os.environ (django-environ.readthedocs.io)；

• dynaconf：分層配置系統，支持多格式配置文件（TOML/YAML/JSON/INI）、Vault/Redis、環境變量覆蓋和 CLI 工具 (dynaconf.com, dynaconf.readthedocs.io)；

• Pydantic BaseSettings：利用類型注解和校驗，從環境變量或 .env 文件自動生成配置對象，并內建校驗功能 (docs.pydantic.dev)。

下面將逐一介紹這些方案的特點、安裝與使用示例，并給出選型建議與最佳實踐。

---

1. 標準庫：os.environ

特點

• 直接映射操作系統的環境變量為字典接口，無額外依賴 (GeeksforGeeks)。

• 適用于簡單腳本或少量變量的場景。

用法

import os# 讀取
DEBUG = os.getenv('DEBUG', 'False') == 'True'
# 或拋錯獲取
DATABASE_URL = os.environ['DATABASE_URL']

局限

• 不支持 .env 文件或類型轉換；

• 管理大量環境變量時難以維護；

• 無法本地化加載，開發調試不便利。

---

2. python-dotenv

安裝

pip install python-dotenv
``` :contentReference[oaicite:7]{index=7}### 主要功能- 從項目根目錄或指定路徑的 `.env` 文件加載鍵值對到 `os.environ`；  
- 支持多行值、變量展開（`${VAR}`）、命令行接口 :contentReference[oaicite:8]{index=8}。  ### 用法示例```python
# app.py
from dotenv import load_dotenv
import os# 自動從當前目錄或上級目錄查找 .env
load_dotenv()SECRET_KEY = os.getenv('SECRET_KEY')
DEBUG = os.getenv('DEBUG', 'False') == 'True'

---

3. python-decouple

安裝

pip install python-decouple
``` :contentReference[oaicite:9]{index=9}### 主要功能- 嚴格分離設置與代碼：支持 INI 或 `.env` 文件；  
- 自動類型轉換（`int`, `bool`, `list` 等）；  
- 默認值與必需參數校驗；  
- 單一配置模塊管理所有環境 :contentReference[oaicite:10]{index=10}。  ### 用法示例```ini
# .env
DEBUG=True
SECRET_KEY=abc123
TIMEOUT=30

# settings.py
from decouple import config, CsvDEBUG = config('DEBUG', default=False, cast=bool)
SECRET_KEY = config('SECRET_KEY')
ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='', cast=Csv())
TIMEOUT = config('TIMEOUT', default=10, cast=int)

---

4. environs

安裝

pip install environs
``` :contentReference[oaicite:11]{index=11}### 主要功能- 類型安全的變量解析（支持 `list`、`datetime`、`URL` 等多種類型）；  
- 讀取 `.env` 文件到 `os.environ`；  
- 支持前綴過濾、變量展開、延遲驗證；  
- 與 Flask、Django 集成 :contentReference[oaicite:12]{index=12}。  ### 用法示例```python
from environs import Envenv = Env()
# 讀取 .env
env.read_env()DEBUG = env.bool("DEBUG", default=False)
DATABASE_URL = env.str("DATABASE_URL")
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=["*"])

---

5. django-environ

安裝

pip install django-environ
``` :contentReference[oaicite:13]{index=13}### 主要功能- 專為 Django 設計，解析數據庫、緩存、郵件等 URL 格式配置；  
- 讀取 `.env` 文件并填充 `os.environ`；  
- 簡化 Django `settings.py` 的多環境管理。  ### 用法示例```python
# settings.py
import environenv = environ.Env(DEBUG=(bool, False))
# 從項目根目錄加載 .env
environ.Env.read_env()DEBUG = env('DEBUG')
DATABASES = {'default': env.db()}         # 解析 DATABASE_URL
CACHES = {'default': env.cache()}         # 解析 CACHE_URL
SECRET_KEY = env('SECRET_KEY')

---

6. dynaconf

安裝

pip install dynaconf
``` :contentReference[oaicite:14]{index=14}### 主要功能- 支持多種配置格式：TOML（推薦）、YAML、JSON、INI、Python 文件；  
- 分層環境 (`[default]`, `[development]`, `[production]`)；  
- 環境變量覆蓋與 `.env` 文件支持；  
- 可選 Vault、Redis 等外部存儲；  
- CLI 工具 (`dynaconf init`, `dynaconf list`, `dynaconf export`)；  
- Flask/Django 擴展；  
- 校驗與特性開關。 :contentReference[oaicite:15]{index=15}### 用法示例```bash
# 初始化項目
dynaconf init -f toml

# settings.toml
[default]
DEBUG = true
[production]
DEBUG = false

# config.py
from dynaconf import Dynaconfsettings = Dynaconf(settings_files=['settings.toml', '.secrets.toml'],environments=True,
)
# 使用
print(settings.DEBUG)

---

7. Pydantic BaseSettings

安裝

pip install pydantic-settings
``` :contentReference[oaicite:16]{index=16}### 主要功能- 利用 Pydantic 模型與類型注解，自動載入環境變量或 `.env` 文件；  
- 內建類型校驗與默認值；  
- 支持多源（環境、文件、命令行）；  
- 易于測試，可通過 `_env_file` 參數指定 `.env` 路徑 :contentReference[oaicite:17]{index=17}。  ### 用法示例```python
from pydantic_settings import BaseSettings, SettingsConfigDictclass Settings(BaseSettings):DEBUG: bool = FalseDATABASE_URL: strmodel_config = SettingsConfigDict(env_file=".env")# 全局單例獲取
settings = Settings()
print(settings.DATABASE_URL)

---

最佳實踐

1. 不將 .env 文件提交到 VCS，使用 .env.example 提供模板；

2. 在 CI/CD 中安全注入環境變量，避免明文出現在日志；

3. 使用單一配置入口（如 config.py 或 settings.py），集中管理；

4. 對必需變量進行啟動時校驗，及早發現配置缺失；

5. 在大型項目中推薦分層或工廠模式（如 Dynaconf 環境分層、應用工廠模式）以利擴展；

6. 注重類型與驗證，優先選擇 Pydantic、Environs 等支持自動校驗的庫。

通過上述工具和實踐，你可以為不同規模和需求的 Python 應用，選用最合適的環境變量管理方案，確保配置安全、可維護且易于切換。