Settings 設定管理
pydantic-settings 是 Pydantic 官方的設定管理套件，讓你用一個 BaseSettings 類別描述應用程式需要的設定，並自動從環境變數、.env 檔與 secrets 目錄讀取，同時做型別驗證。設定寫錯（例如 PORT=abc）時，程式在啟動時就會報錯，而不是執行到一半才出問題。本頁說明安裝、基本用法、.env、巢狀設定與實務建議。
如何安裝 pydantic-settings？
pydantic-settings 是獨立套件，需要另外安裝：
最基本的用法是什麼？
import os
from pydantic import SecretStr
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
app_name: str = "My App"
debug: bool = False
port: int = 8000
database_url: str
api_key: SecretStr
# 模擬環境變數；實務上由系統、Docker 或 CI 設定
os.environ["DATABASE_URL"] = "postgresql://localhost/mydb"
os.environ["API_KEY"] = "sk-123"
os.environ["PORT"] = "9000"
settings = Settings()
print(settings.port) # 9000（字串已轉成 int）
print(settings.api_key) # **********
讀取規則：
- 環境變數名稱不分大小寫，
PORT、port都能對應到port欄位。 - 環境變數的值一定是字串，Pydantic 依欄位型別轉換；
bool接受true/false/1/0/yes/no。 - 沒有預設值的欄位（
database_url、api_key）是必填，環境變數缺少時建立Settings()就會丟出ValidationError。
如何讀取 .env 檔？
透過 SettingsConfigDict 指定 .env 檔、前綴與編碼：
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
env_prefix="MYAPP_", # 只讀取 MYAPP_ 開頭的變數
extra="ignore", # .env 中多出的變數不報錯
)
debug: bool = False
database_url: str = "sqlite:///./dev.db"
不要把 .env 提交到 Git
.env 通常含有密碼與 API 金鑰，請加進 .gitignore。另外提交一份不含真實值的 .env.example 給團隊參考。
優先順序（高到低）：建立時直接傳入的參數 → 環境變數 → .env 檔 → secrets 目錄 → 欄位預設值。所以正式環境的環境變數會覆蓋開發用的 .env。
巢狀設定要怎麼寫？
把相關設定分組成子模型，再用 env_nested_delimiter 指定分隔符號：
import os
from pydantic import BaseModel
from pydantic_settings import BaseSettings, SettingsConfigDict
class DatabaseConfig(BaseModel):
host: str = "localhost"
port: int = 5432
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_nested_delimiter="__")
db: DatabaseConfig = DatabaseConfig()
os.environ["DB__HOST"] = "db.internal"
os.environ["DB__PORT"] = "6543"
print(Settings().db) # host='db.internal' port=6543
實務上怎麼在專案中使用設定？
建立一次、全專案共用。常見做法是用 functools.lru_cache 包一個取得設定的函式，避免每次都重新讀檔：
from functools import lru_cache
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
debug: bool = False
@lru_cache
def get_settings() -> Settings:
return Settings()
FastAPI 中可以把 get_settings 當作依賴注入（Depends(get_settings)），測試時再用 app.dependency_overrides 換成測試設定。
推薦影音
BugBytes：pydantic-settings 型別安全的設定管理
簡述：約 18 分鐘，示範定義 BaseSettings 類別、從作業系統環境變數與 .env 檔讀取設定，並確保各種型別的型別安全，對應本頁前兩節。
James Clare：Pydantic Settings & Environment Variables
簡述：約 7 分鐘的短版入門（系列第 6 集），快速看過 Pydantic Settings 模組的用法，適合先建立整體印象。