Laravel自动化部署时DotEnv无法读取服务器环境变量 缺失APP_KEY报500错误

Laravel 本身支持直接读取系统层面的环境变量，但存在多个前置限制条件，并非配置了系统环境变量就能直接生效。你遇到的Illuminate\Encryption\MissingAppKeyException错误，几乎都是以下几个常见原因导致的：

快速验证排查步骤 #

先确认问题出在Web运行环境层面，还是Laravel配置层面：

• 在项目根目录新建临时文件info.php，写入内容：<?php echo "当前APP_KEY值：" . (getenv('APP_KEY') ?: '空') . "<br>"; phpinfo(INFO_ENVIRONMENT);
• 通过Web浏览器访问该文件，如果输出的APP_KEY为空，且phpinfo的环境变量列表中找不到APP_KEY，说明是Web运行环境未加载到该变量，与Laravel无关；如果phpinfo中能看到APP_KEY，但Laravel仍报错，才是Laravel自身配置的问题。
• 排查完成后务必删除该info.php文件，避免敏感信息泄露。

常见原因及对应解决方法 #

1. PHP-FPM/CGI 运行环境默认不继承系统全局环境变量 #

这是概率最高的原因：

• 你SSH登录后执行env看到的环境变量，仅对当前SSH会话用户（比如root、你的个人登录账号）生效，属于会话级变量
• Laravel 实际运行在Web服务驱动的PHP进程中（比如Nginx+PHP-FPM、Apache+CGI），这类进程的运行用户一般为www-data、nginx这类系统服务用户，默认会主动隔离系统环境变量
• 尤其是PHP-FPM默认开启clear_env = On配置，会清空所有来自系统的环境变量，仅加载FPM配置文件中通过env[KEY] = VALUE显式定义的变量

对应解决方法：

根据你的运行环境选择：

• 使用PHP-FPM的场景：编辑对应PHP版本的FPM池配置（一般路径为/etc/php/[版本号]/fpm/pool.d/www.conf），将clear_env = no，或直接在该配置中显式添加env[APP_KEY] = 你的实际APP_KEY值，修改后重启PHP-FPM服务即可
• 使用Apache作为Web服务的场景：可在站点配置中通过SetEnv APP_KEY 你的实际APP_KEY值定义变量，或修改php.ini的variables_order确保包含S，启用系统环境变量加载

2. 已生成Laravel配置缓存 #

Laravel 一旦执行过php artisan config:cache生成配置缓存，会完全停止读取任何环境变量（包括.env文件和系统环境变量），所有配置都会从缓存文件bootstrap/cache/config.php中读取：

• 你没有.env文件的情况下，如果执行过config:cache，生成的缓存中APP_KEY自然为空，哪怕后续在服务器层面配置了正确的环境变量，也不会生效

对应解决方法：

• 先清除已有配置缓存：执行php artisan config:clear，或直接删除bootstrap/cache/config.php文件
• 生产环境推荐保留配置缓存优化性能，需在确保Web运行环境能正常读取到系统环境变量的前提下，重新执行php artisan config:cache，让缓存写入正确的APP_KEY值

3. 环境变量定义的作用域不符合要求 #

如果你是直接在SSH终端执行export APP_KEY=xxx定义的变量，仅对当前SSH会话生效，Web服务进程完全无法读取。

对应解决方法：

若要让所有系统进程读取到全局环境变量，需将定义写入系统级环境变量文件：

• 全局对所有用户生效：写入/etc/environment，格式为APP_KEY=你的实际值
• 仅对Web运行用户（如www-data）生效：写入/home/www-data/.bashrc，或/etc/profile.d/目录下的自定义脚本，执行source命令重新加载后生效

额外注意事项 #

Laravel 官方明确限制：env() 函数只能在config/目录下的配置文件中使用，严禁在业务代码（控制器、中间件、服务提供者等）中直接调用env()。只要生成了配置缓存，业务代码中调用env()都会返回null，这也是很多环境变量读取异常的隐性原因。

内容的提问来源于stack exchange，提问作者TheSteed