Laravel部署至AWS Elastic Beanstalk缓存配置时触发500错误

部署Laravel应用到AWS Elastic Beanstalk后，执行php artisan config:cache时网站触发500服务器错误，不缓存配置则运行完全正常。通过SSH登录实例执行php artisan optimize:clear清除缓存后问题可解决，但无法在缓存配置状态下维持正常运行。

部署配置文件（.ebextensions） #

option_settings:
-
    namespace: aws:elasticbeanstalk:application:environment
    option_name: COMPOSER_HOME
    value: /root

-
    namespace: aws:elasticbeanstalk:container:php:phpini
    option_name: document_root
    value: /public

container_commands:
    01-no_dev:
        command: "composer.phar install --optimize-autoloader --no-dev"
        cwd: "/var/app/staging"
    02-storage_permission:
        command: "chmod -R 755 ./storage"
    03-bootstrap_permission:
        command: "chmod -R 755 ./bootstrap/cache/"
    05-view_cache:
        command: "php artisan view:cache"
    06-config_cache:
        command: "php artisan config:cache"
    07-route_cache:
        command: "php artisan route:cache"
    08-migrate_db:
        command: "php artisan migrate --force"
    09-seed_db:
        command: "php artisan db:seed --force"
    10-npm:
        command: "sudo npm install"
    11-npm_dependencies:
        command: "sudo npm run build"

files:
    /opt/elasticbeanstalk/tasks/taillogs.d/laravel-logs.conf:
        content: /var/app/current/storage/logs/laravel.log
        group: root
        mode: "000755"
        owner: root

Nginx配置片段 #

location / {
try_files $uri $uri/ /index.php?$query_string;
gzip_static on;
}

排查与解决方案 #

1. 环境变量未正确加载 #

执行config:cache后，Laravel会将所有配置打包缓存，不再读取本地.env文件，必须确保所有Laravel依赖的环境变量（如APP_KEY、DB_HOST、APP_URL等）已添加到Elastic Beanstalk环境配置中：

• 进入Elastic Beanstalk控制台，打开「配置」>「软件」>「环境属性」，检查并补全所有必需变量。
• 确认container_commands执行时环境变量已生效（Elastic Beanstalk默认会在执行容器命令前加载环境变量）。

2. 缓存文件权限不兼容 #

container_commands默认以root用户执行，生成的缓存文件所属用户为root，但Nginx/php-fpm进程通常以webapp用户运行，导致无法读取缓存文件。修改缓存相关命令，切换为webapp用户执行：

05-view_cache:
    command: "sudo -u webapp php artisan view:cache"
06-config_cache:
    command: "sudo -u webapp php artisan config:cache"
07-route_cache:
    command: "sudo -u webapp php artisan route:cache"

3. 配置文件存在动态逻辑错误 #

缓存配置时Laravel会执行所有配置文件的代码，若配置中存在依赖未缓存状态的动态逻辑（比如深层嵌套使用env()函数），会导致缓存失败：

• 统一配置文件写法：先通过env()获取值并赋值给变量，再在配置数组中使用变量，示例：

  // 错误写法
  return [
      'api_url' => env('APP_URL') . '/v1'
  ];
  
  // 正确写法
  $appUrl = env('APP_URL');
  return [
      'api_url' => $appUrl . '/v1'
  ];
  

• 执行php artisan config:cache时若有语法错误，会写入Laravel日志，可通过tail /var/app/current/storage/logs/laravel.log查看详情。

4. 部署顺序逻辑冲突 #

当前配置中config:cache在数据库迁移前执行，若配置依赖数据库连接，会因数据库未初始化导致配置加载失败。调整命令顺序，将缓存操作移到数据库操作之后：

container_commands:
    01-no_dev:
        command: "composer.phar install --optimize-autoloader --no-dev"
        cwd: "/var/app/staging"
    02-storage_permission:
        command: "chmod -R 755 ./storage"
    03-bootstrap_permission:
        command: "chmod -R 755 ./bootstrap/cache/"
    08-migrate_db:
        command: "php artisan migrate --force"
    09-seed_db:
        command: "php artisan db:seed --force"
    05-view_cache:
        command: "sudo -u webapp php artisan view:cache"
    06-config_cache:
        command: "sudo -u webapp php artisan config:cache"
    07-route_cache:
        command: "sudo -u webapp php artisan route:cache"
    10-npm:
        command: "sudo npm install"
    11-npm_dependencies:
        command: "sudo npm run build"

5. 查看详细错误日志 #

500错误的具体原因可通过日志定位：

• 在Elastic Beanstalk控制台「日志」>「请求日志」>「最近的日志」下载查看完整日志。
• SSH登录实例后执行tail -f /var/app/current/storage/logs/laravel.log，实时查看错误输出。

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