Laravel Docker环境下PHP请求出现500内部服务器错误排查

问题背景 #

Docker中运行的Laravel项目，访问PHP文件（如GET /index.php）时返回500错误，HTML文件可正常加载，采用Nginx+PHP-FPM架构。

现有配置 #

Nginx配置（site.conf） #

upstream backend {
    server web:9000;  # PHP-FPM service
}

server {
    listen 80;
    index index.php index.html;
    server_name domain_name;
    error_log /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/html/public;

    client_max_body_size 100M;
    fastcgi_read_timeout 1800;

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

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+?\.php)(/.*)$;
        fastcgi_pass backend;  # Use the upstream backend
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

Docker Compose配置（docker-compose.yml） #

version: '3.8'

services:
  db:
    image: mysql:latest
    ports:
      - 3306:3306
    env_file:
      - ./.env
    volumes:
      - db-data:/var/lib/mysql

  nginx:
    image: nginx:stable-alpine
    ports:
      - 80:80
    volumes:
      - ./docker/nginx/site.conf:/etc/nginx/conf.d/default.conf
      - ./docker/logs/nginx:/var/log/nginx
    depends_on:
      - web

  web:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ${APP_NAME}_php
    volumes:
      - ./:/var/www/html
    env_file:
      - ./.env
    ports:
      - 9001:9000
    depends_on:
      - db

volumes:
  db-data:

Dockerfile #

FROM php:8.3-fpm

# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libonig-dev \
    libzip-dev \
    unzip \
    git \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd pdo pdo_mysql mbstring zip

# Set working directory
WORKDIR /var/www/html

# Copy application code
COPY . .

# Install Composer
COPY --from=composer:2.7 /usr/bin/composer /usr/bin/composer

# Install PHP dependencies
RUN composer install

Laravel日志片段 #

tail -n 10 laravel.log
#25 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Exceptions/Handler.php(490): Illuminate\Foundation\Exceptions\Handler->renderHttpException(Object(Symfony\Component\HttpKernel\Exception\HttpException))
#26 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Exceptions/Handler.php(356): Illuminate\Foundation\Exceptions\Handler->prepareResponse(Object(Illuminate\Http\Request), Object(Symfony\Component\HttpKernel\Exception\HttpException))
#27 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(196): Illuminate\Foundation\Exceptions\Handler->render(Object(Illuminate\Http\Request), Object(ArgumentCountError))
#28 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(173): Illuminate\Foundation\Bootstrap\HandleExceptions->renderHttpResponse(Object(ArgumentCountError))
#29 [internal function]: Illuminate\Foundation\Bootstrap\HandleExceptions->handleException(Object(ArgumentCountError))
#30 {main}
  thrown at /var/www/html/vendor/laravel/framework/src/Illuminate/Support/Manager.php:94)
[stacktrace]
#0 {main}
"}

已完成的排查步骤 #

• 确认/var/www/html/public目录存在index.php文件
• 验证Nginx和PHP-FPM容器运行状态正常
• 检查过文件权限与归属

排查方案与修复建议 #

1. 定位ArgumentCountError根源 #

日志显示错误类型为ArgumentCountError，属于PHP代码层面的参数不匹配问题，需查看完整日志获取具体错误信息：

# 在web容器中执行
docker exec -it ${APP_NAME}_php tail -n 50 /var/www/html/storage/logs/laravel.log

找到日志开头的错误详情，比如“Too few arguments to function X, Y passed and Z expected”，定位到具体的方法调用。

2. 验证Laravel与PHP版本兼容性 #

当前使用PHP 8.3，需确认Laravel版本是否支持：

• Laravel 10.x及以上版本支持PHP 8.3
• 若Laravel版本过低，需升级框架或降低PHP版本（如PHP 8.2）

3. 清除Laravel缓存 #

缓存的配置/路由可能导致运行时错误，执行以下命令：

docker exec -it ${APP_NAME}_php php artisan config:clear
docker exec -it ${APP_NAME}_php php artisan cache:clear
docker exec -it ${APP_NAME}_php php artisan route:clear
docker exec -it ${APP_NAME}_php php artisan view:clear

4. 检查.env配置 #

确认.env文件中APP_KEY存在，若缺失则生成：

docker exec -it ${APP_NAME}_php php artisan key:generate

5. 验证文件可写权限 #

确保Laravel的storage和bootstrap/cache目录可被PHP-FPM进程（www-data用户）读写：

docker exec -it ${APP_NAME}_php chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
docker exec -it ${APP_NAME}_php chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

6. 排查Nginx与PHP-FPM连接情况 #

检查Nginx错误日志，确认是否存在PHP-FPM连接问题：

docker exec -it <nginx-container-name> cat /var/log/nginx/error.log

查看PHP-FPM容器日志，确认是否有进程错误：

docker logs ${APP_NAME}_php

7. 验证Composer依赖一致性 #

因Dockerfile中构建时执行了composer install，但本地目录挂载覆盖了容器内文件，需确保本地已安装依赖且版本一致：

composer install

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