Django 项目加载 .env 实时生效方法

本文详解 Django 项目中通过 django-environ 加载 .env 文件的完整流程，涵盖环境配置、变量读取、服务重启要点及常见失效原因，确保修改后立即生效。

本文详解 Django 项目中通过 django-environ 加载 .env 文件的完整流程，涵盖环境配置、变量读取、服务重启要点及常见失效原因，确保修改后立即生效。

Django 本身不原生支持 .env 文件，因此仅将变量写入 .env 并重启开发服务器（如 python manage.py runserver）是无效的——Django 不会自动读取或解析该文件。要使 .env 中的变量真正生效，必须借助第三方库（如 django-environ）显式加载，并确保加载时机正确、路径准确、值被合理引用。

✅ 正确配置步骤

1. 安装依赖

   pip install django-environ

2. 在 settings.py 中初始化环境读取
   在 BASE_DIR 定义之后、任何使用环境变量之前（推荐紧接其后），添加以下代码：

   import os
   import environ
   
   # 初始化 environ 实例
   env = environ.Env()
   # 从项目根目录下的 .env 文件读取变量（注意：路径需准确）
   environ.Env.read_env(os.path.join(BASE_DIR, '.env'))

   ⚠️ 注意：os.path.join(BASE_DIR, '.env') 是标准做法；若 .env 位于其他位置（如与 manage.py 同级），请相应调整路径，例如 os.path.join(BASE_DIR, '..', '.env')，并确保路径存在且可读。

3. 安全读取变量并设置默认值
   使用 env('KEY', default='fallback') 或 os.environ.get() 均可，但推荐 env() ——它支持类型转换（如 env.bool('DEBUG', default=False)）和更清晰的错误提示：

   DEBUG = env.bool('DEBUG', default=False)
   SECRET_KEY = env('SECRET_KEY', default='insecure-key-for-dev')
   
   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.postgresql',
           'NAME': env('DB_NAME'),
           'USER': env('DB_USER'),
           'PASSWORD': env('DB_PASSWORD'),
           'HOST': env('DB_HOST', default='localhost'),
           'PORT': env.int('DB_PORT', default=5432),
       }
   }

? 为什么重启后仍不生效？关键排查点

• 未真正重启服务：Django 开发服务器启用 --reload（默认开启）时，仅监视 Python 文件变更，不会监听 .env 文件变化。务必手动终止进程（Ctrl+C）并重新运行 python manage.py runserver。
• 缓存干扰：Django 的模板、数据库查询等缓存不影响环境变量读取，clear_cache 命令与此无关；但若使用了 django-compressor 或自定义配置缓存，请确认其未固化旧配置。
• 多环境覆盖：检查是否在 settings.py 后续逻辑中硬编码覆盖了环境变量（如 DEBUG = True），导致 .env 设置被忽略。
• 权限与路径错误：运行命令的用户需有读取 .env 的权限；使用 print(os.path.exists(...)) 验证路径是否存在。

✅ 验证是否加载成功（调试建议）

在 settings.py 底部临时添加：

print("✅ Loaded DB_NAME:", env('DB_NAME', default='[NOT SET]'))
print("✅ DEBUG is:", DEBUG)

启动服务时观察终端输出，确认值符合预期。

? 最佳实践总结

• 将 .env 文件加入 .gitignore，杜绝敏感信息泄露；
• 生产环境应使用系统级环境变量（如 export DB_NAME=prod_db），而非 .env 文件；
• 对关键变量（如 SECRET_KEY, DEBUG）始终提供安全默认值或强制校验（env('SECRET_KEY') 抛异常若缺失）；
• 使用 env.db_url() 可直接解析 DATABASE_URL=postgresql://... 格式，简化数据库配置。

完成上述配置后，每次修改 .env 文件，只需彻底重启 Django 开发服务器，新值即可即时生效——无需额外缓存清理或复杂钩子。