本文详解 django 项目中通过 django-environ 加载 .env 文件的完整流程，涵盖环境配置、变量读取、服务重启要点及常见失效原因，确保修改后立即生效。
本文详解 django 项目中通过 django-environ 加载 .env 文件的完整流程，涵盖环境配置、变量读取、服务重启要点及常见失效原因，确保修改后立即生效。
Django 本身不原生支持 .env 文件，因此仅将变量写入 .env 并重启开发服务器（如 python manage.py runserver）是无效的——Django 不会自动读取或解析该文件。要使 .env 中的变量真正生效，必须借助第三方库（如 django-environ）显式加载，并确保加载时机正确、路径准确、值被合理引用。
✅ 正确配置步骤
-
安装依赖
pip install django-environ
-
在 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')，并确保路径存在且可读。
Django Unfold下载提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
-
安全读取变量并设置默认值
使用 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 开发服务器，新值即可即时生效——无需额外缓存清理或复杂钩子。
