Symfony 6.1下.env.local无法覆盖.env已设置环境变量的问题

核心原因 #

按出现概率从高到低排序：

• 项目根目录存在预编译生成的环境变量缓存文件：.env.local.php或.env.php。Symfony一旦检测到这两个文件存在，会直接加载文件内预存的变量值，完全跳过.env、.env.local等所有源env文件的读取。这类文件一般是执行composer dump-env做部署优化时自动生成的，哪怕是本地开发环境，只要文件存在就会触发最高优先级加载。
• 入口文件的Dotenv初始化逻辑被篡改。Symfony默认通过bootEnv()方法按优先级加载env文件，自动处理高优先级文件对低优先级文件的变量覆盖；如果手动改成了调用load()方法逐个加载env文件，load()的默认逻辑是遇到已存在的变量就直接跳过，先加载的.env变量会占住位置，后续.env.local的同名值就不会生效。另外如果手动给loadEnv()/bootEnv()传参关闭了覆盖开关，也会出现这个问题。
• 待覆盖的变量已经在外部环境提前定义：比如PHP-FPM池配置、Nginx/Apache虚拟主机配置、系统全局环境变量里已经设了同名变量，Symfony的Dotenv组件默认不会覆盖外部传入的环境变量，不管.env.local里写什么值都不会生效。
• 配置缓存未更新：修改.env.local后，因为文件权限、debug模式关闭等原因，Symfony没有自动刷新配置缓存，旧的配置值一直被复用。
• 低级错误：.env.local文件名写错（比如Windows开了隐藏扩展名导致实际存成.env.local.txt）、文件权限不足导致PHP进程无法读取，文件根本没被加载。

解决步骤 #

按顺序排查处理即可：

1. 首先直接删除项目根目录下的.env.local.php和.env.php两个文件，90%的场景下这一步就能解决问题。如果是生产环境需要用预编译优化提升性能，等所有env文件修改完成后，重新执行对应环境的编译命令（比如生产环境执行composer dump-env prod）重新生成预编译文件即可。
2. 校验两个入口文件的Dotenv初始化代码，确保是默认逻辑：
   • Web入口public/index.php
   • 命令行入口bin/console
     两个文件里的Dotenv加载代码应该和下面一致，没有被手动修改：

   use Symfony\Component\Dotenv\Dotenv;
   
   require dirname(__DIR__).'/vendor/autoload.php';
   
   if (!isset($_SERVER['APP_ENV']) && !isset($_ENV['APP_ENV'])) {
       if (!class_exists(Dotenv::class)) {
           throw new RuntimeException('Application environment is not set.');
       }
       (new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
   }
   

   如果确实需要自定义加载逻辑，记得加载高优先级env文件时调用overload()方法而非load()，强制覆盖已存在的同名变量。
3. 检查变量来源：执行命令php bin/console debug:container --env-vars，找到你要覆盖的变量，如果显示来源为external，说明变量是从服务器/PHP配置层面传入的，需要到对应的PHP-FPM配置、Web服务器虚拟主机配置里修改或删除这个外部变量，才能让env文件里的值生效。同时可以执行php bin/console debug:dotenv查看实际被加载的env文件列表，确认.env.local在加载列表中，排除文件名错误、权限不足的问题。
4. 手动清理缓存：执行php bin/console cache:clear，如果是之前切过prod环境，加环境参数执行php bin/console cache:clear --env=prod，确保旧的配置缓存被完全清除。

内容的提问来源于stack exchange，提问作者Luboš Remplík