环境变量是操作系统中存储配置信息的键值对，用于在不同环境（开发/测试/生产）中切换配置，避免敏感信息（密码、密钥）硬编码在代码中。

一、配置环境变量的方式

1. 操作系统级别设置

Linux/macOS

# 临时设置（当前终端会话有效）
export DATABASE_URL="postgresql://localhost/mydb"
export API_KEY="sk-123456"

# 永久设置（写入配置文件）
echo 'export DATABASE_URL="postgresql://localhost/mydb"' >> ~/.bashrc   # 或 ~/.zshrc
source ~/.bashrc

# 查看环境变量
echo $DATABASE_URL
env | grep DATABASE

Windows (CMD)

# 临时设置
set DATABASE_URL=postgresql://localhost/mydb

# 永久设置（通过系统设置）
setx DATABASE_URL "postgresql://localhost/mydb"

Windows (PowerShell)

# 临时设置
$env:DATABASE_URL="postgresql://localhost/mydb"

# 永久设置
[Environment]::SetEnvironmentVariable("DATABASE_URL", "postgresql://localhost/mydb", "User")

2. 使用 .env 文件（推荐）

.env 文件是项目级别的环境变量配置，应该被添加到 .gitignore 中，避免提交到版本控制。

# .env 文件示例
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=sk-1234567890
DEBUG=true
SECRET_KEY=your-secret-key-here
REDIS_URL=redis://localhost:6379/0

3. 使用 python-dotenv 读取 .env

# 安装依赖
pip install python-dotenv

# 方式1：自动查找 .env 文件
from dotenv import load_dotenv
import os

load_dotenv()  # 加载 .env 文件

db_url = os.getenv("DATABASE_URL")
api_key = os.environ.get("API_KEY")

# 方式2：指定 .env 文件路径
load_dotenv("/path/to/.env.production")

# 方式3：覆盖已有的环境变量
load_dotenv(override=True)

4. IDE 中配置（PyCharm / VS Code）

PyCharm

1. Run → Edit Configurations

2. Environment variables 中添加 KEY=VALUE

3. 或点击 ... 图标批量添加

VS Code

在 .vscode/launch.json 中配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "env": {
                "DATABASE_URL": "postgresql://localhost/mydb",
                "API_KEY": "sk-123456"
            }
        }
    ]
}

5. Docker 容器中配置

# 方式1：-e 参数
docker run -e DATABASE_URL="postgresql://db/mydb" myapp

# 方式2：--env-file 参数
docker run --env-file .env myapp

# 方式3：docker-compose.yml

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    environment:
      - DATABASE_URL=postgresql://db/mydb
      - API_KEY=${API_KEY}  # 从宿主机环境变量传入
    env_file:
      - .env

二、读取环境变量的方式

1. 基础读取（os.environ）

import os

# 获取环境变量（不存在返回 None）
db_url = os.environ.get("DATABASE_URL")
print(db_url)

# 获取环境变量（不存在时使用默认值）
api_key = os.environ.get("API_KEY", "default-key")

# 直接访问（不存在会抛出 KeyError）
debug = os.environ["DEBUG"]

# 检查环境变量是否存在
if "DATABASE_URL" in os.environ:
    print("已配置数据库连接")

2. 类型转换

import os

# 字符串转布尔值
debug = os.getenv("DEBUG", "false").lower() == "true"

# 字符串转整数
port = int(os.getenv("PORT", "8080"))

# 字符串转列表
allowed_hosts = os.getenv("ALLOWED_HOSTS", "").split(",")

# 使用更强大的库：python-decouple
from decouple import config

DEBUG = config("DEBUG", default=False, cast=bool)
PORT = config("PORT", default=8080, cast=int)

3. 使用 os.getenv() 简写

import os

# os.getenv() 不存在返回 None，与 os.environ.get() 相同
db_url = os.getenv("DATABASE_URL")

# 设置默认值
api_key = os.getenv("API_KEY", "default-key")

三、项目示例

项目结构

myproject/
├── .env                # 环境变量文件（不提交到 Git）
├── .env.example        # 环境变量模板（提交到 Git）
├── .gitignore          # 忽略 .env
├── config.py           # 配置读取模块
├── main.py
└── requirements.txt

.env 文件

# 环境标识
ENVIRONMENT=development
DEBUG=true

# 数据库配置
DATABASE_URL=postgresql://localhost:5432/mydb
DATABASE_POOL_SIZE=10

# API 配置
API_KEY=sk-test-123456
API_SECRET=test-secret

# Redis 配置
REDIS_URL=redis://localhost:6379/0

# 应用配置
SECRET_KEY=your-secret-key
ALLOWED_HOSTS=localhost,127.0.0.1

.env.example 文件（提交到 Git）

# 环境标识
ENVIRONMENT=development
DEBUG=false

# 数据库配置
DATABASE_URL=postgresql://localhost:5432/mydb
DATABASE_POOL_SIZE=10

# API 配置
API_KEY=
API_SECRET=

# Redis 配置
REDIS_URL=redis://localhost:6379/0

# 应用配置
SECRET_KEY=change-this-in-production
ALLOWED_HOSTS=localhost,127.0.0.1

config.py - 配置管理模块

import os
from dotenv import load_dotenv
from pathlib import Path

# 加载 .env 文件
# 优先使用 .env 文件，如果没有则使用环境变量
env_file = Path(".env")
if env_file.exists():
    load_dotenv(env_file)

class Config:
    """应用配置类"""
    
    # 环境配置
    ENVIRONMENT = os.getenv("ENVIRONMENT", "production")
    DEBUG = os.getenv("DEBUG", "false").lower() == "true"
    
    # 数据库配置
    DATABASE_URL = os.getenv("DATABASE_URL")
    DATABASE_POOL_SIZE = int(os.getenv("DATABASE_POOL_SIZE", "10"))
    
    # API 配置
    API_KEY = os.getenv("API_KEY")
    API_SECRET = os.getenv("API_SECRET")
    
    # Redis 配置
    REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")
    
    # 应用配置
    SECRET_KEY = os.getenv("SECRET_KEY")
    ALLOWED_HOSTS = os.getenv("ALLOWED_HOSTS", "").split(",")
    
    @classmethod
    def validate(cls):
        """验证必要的配置是否存在"""
        required = ["DATABASE_URL", "SECRET_KEY"]
        missing = [key for key in required if not getattr(cls, key)]
        if missing:
            raise ValueError(f"缺少必要的环境变量: {', '.join(missing)}")
        return True

# 实例化配置
config = Config()

.gitignore 文件

# 环境变量文件
.env
.env.local
.env.*.local

# Python 缓存
__pycache__/
*.pyc

main.py - 使用配置

from config import config

# 验证配置
config.validate()

print(f"环境: {config.ENVIRONMENT}")
print(f"调试模式: {config.DEBUG}")
print(f"数据库: {config.DATABASE_URL}")
print(f"允许的主机: {config.ALLOWED_HOSTS}")

# 在应用中使用
if config.DEBUG:
    print("开发环境启动...")
else:
    print("生产环境启动...")

五、其他

原则	说明
不要硬编码	敏感信息永远不要写在代码里
使用 .env	开发环境推荐使用 .env 文件
提交 .env.example	提供配置模板，但不提交真实值
忽略 .env	确保 .env 在 .gitignore 中
提供默认值	使用 os.getenv("KEY", "default") 提供默认值
类型转换	注意环境变量都是字符串，需要手动转换
验证必要配置	启动时检查必要的环境变量是否存在

备注：多环境下用不同 .env 文件，使用 pydantic 配置更安全。