环境变量是现代后端开发中不可或缺的幕后英雄。无论是构建最小可行产品（MVP），还是部署一个生产就绪的 FastAPI 应用，通过环境变量管理配置可以确保安全性、灵活性和可移植性。

在本指南中，我们将探讨在 FastAPI 中处理环境变量的清晰、可扩展且适合生产环境的方法，使用诸如 .env 文件、python-dotenv 和强大的 pydantic-settings 等工具。

为什么使用环境变量？

将凭据或设置硬编码到代码中是一个巨大的安全风险。想象一下，如果你将带有数据库密码的代码推送到 GitHub 上，那可就糟糕了！

使用环境变量可以让你：

将敏感数据排除在版本控制之外。

在开发、预发布和生产环境之间无缝切换。

保持更清晰、更易读的代码。

选项 1：使用 .env + python-dotenv 的基本设置

这种方法非常适合快速设置和本地开发。

第 1 步：安装包

pip install python-dotenv

第 2 步：在项目根目录创建 .env 文件

DEBUG=True

DATABASE_URL=postgresql://user:pass@localhost/db

SECRET_KEY=super-secret-key

注意：千万不要将 .env 文件提交到 Git 中！请将其添加到 .gitignore 文件中。

第 3 步：在代码中加载变量

# main.py

from dotenv import load_dotenv

import os

load_dotenv()  # 将 .env 文件内容加载到环境中

DEBUG = os.getenv("DEBUG", "False") == "True"

DATABASE_URL = os.getenv("DATABASE_URL")

SECRET_KEY = os.getenv("SECRET_KEY")

你现在可以在 FastAPI 应用中安全地使用这些变量了。

选项 2：使用 pydantic-settings 的现代方式

这种方法强烈推荐用于生产应用和大型团队。它提供了类型安全、验证和默认回退。

第 1 步：安装依赖

pip install pydantic-settings

第 2 步：创建配置类

# config.py

from pydantic_settings import BaseSettings

class Settings(BaseSettings):

    DEBUG: bool = False

    DATABASE_URL: str

    SECRET_KEY: str

    class Config:

        env_file = ".env"

settings = Settings()

第 3 步：在 FastAPI 应用中使用设置

# main.py

from fastapi import FastAPI

from config import settings

app = FastAPI(debug=settings.DEBUG)

@app.get("/")

def read_root():

    return {

        "environment": "development" if settings.DEBUG else "production",

        "db": settings.DATABASE_URL,

    }

简单、清晰且类型安全！

在不同环境之间切换

假设你有不同环境的配置文件，例如：

.env.development

.env.staging

.env.production

你可以根据一个 ENV 环境变量动态加载：

# config.py

import os

from pydantic_settings import BaseSettings

class Settings(BaseSettings):

    DEBUG: bool = False

    DATABASE_URL: str

    SECRET_KEY: str

    class Config:

        env_file = f".env.{os.getenv('ENV', 'development')}"

然后设置你的环境：

ENV=production uvicorn main:app --host 0.0.0.0 --port 8000

建议的项目结构

project/

├── app/

│   ├── main.py

│   ├── config.py

│   └── ...

├── .env.development

├── .env.production

└── requirements.txt

安全提示

将 .env* 添加到 .gitignore 中。

在生产环境中使用部署密钥（如 Docker、GitHub Actions、Heroku）代替 .env 文件。

避免在日志中打印敏感环境变量。

额外福利：在 Docker 中使用

如果你正在容器化你的应用，你可以在 Dockerfile 或使用 docker-compose 的 .env 文件中传递环境变量。

Dockerfile:

ENV DATABASE_URL=postgresql://prod_user:pass@prod/db

docker-compose.yml:

services:

  web:

    build: .

    env_file:

      - .env.production

最后总结

FastAPI 给我们带来了速度，而 Pydantic 则提供了类型安全。将它们与智能的环境变量管理相结合，你的后端应用将更加健壮和安全。