首次执行php artisan migrate报错：could not find driver（mysql连接）

问题背景 #

首次运行php artisan migrate时触发以下错误：

could not find driver (Connection: mysql, SQL: select table_name as name, (data_length + index_length) as size, table_comment as comment, engine as engine, table_collation as collation from information_schema.tables where table_schema = 'laravel' and table_type in ('BASE TABLE', 'SYSTEM VERSIONED') order by table_name)
Context: {"exception":{"errorInfo":null,"connectionName":"mysql"}}

at vendor/monolog/monolog/src/Monolog/Handler/StreamHandler.php:137

已部署正常运行的MariaDB容器，且Dockerfile中已安装pdo_mysql、mysqli扩展，相关配置如下：

docker-compose.yml #

version: '3.1'
services:
    app:
        container_name: app
        build:
            context: .
            dockerfile: Dockerfile
        volumes:
            - .:/var/www/html
        working_dir: /var/www/html
        depends_on:
            - mariadb
        networks:
            - laravel
            - dbnet
    mariadb:
        container_name: mariadb
        image: mariadb:latest
        restart: always
        ports:
            - '3306:3306'
        environment:
            MARIADB_DATABASE: laravel
            MARIADB_ALLOW_EMPTY_ROOT_PASSWORD: yes
        networks:
            - dbnet
            - laravel
        volumes:
            - db_data:/var/lib/mysql

Dockerfile #

# Use an official PHP runtime as a parent image
FROM php:8.3.2-fpm

# Set the working directory to /var/www/html
WORKDIR /var/www/html

# Install dependencies
RUN apt-get update && \
    apt-get install -y \
        libzip-dev \
        unzip

# Install Xdebug
COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/bin/
RUN install-php-extensions xdebug zip pdo_mysql mysqli @composer

# Copy the current directory contents into the container at /var/www/html
COPY . /var/www/html

# Install Laravel dependencies using Composer
RUN composer install
EXPOSE 9000
CMD ["php-fpm"]

.env配置 #

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

config/database.php配置 #

'connections' => [
    'mysql' => [
        'driver' => 'mysql',
        'url' => env('DATABASE_URL'),
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'forge'),
        'username' => env('DB_USERNAME', 'forge'),
        'password' => env('DB_PASSWORD', ''),
        'unix_socket' => env('DB_SOCKET', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'prefix_indexes' => true,
        'strict' => true,
        'engine' => null,
        'options' => extension_loaded('pdo_mysql') ? array_filter([
            PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
        ]) : [],
    ],
],

解决方法 #

1. 修正数据库主机配置 #

在Docker Compose环境中，容器间通过服务名进行网络通信，.env中的DB_HOST设置为localhost会指向Laravel容器自身，而非MariaDB容器。修改.env：

DB_HOST=mariadb

2. 验证PHP扩展是否生效 #

进入Laravel容器执行命令，确认pdo_mysql扩展已加载：

docker exec -it app php -m | grep pdo_mysql

如果无输出，需检查Dockerfile中的扩展安装步骤，可尝试替换为手动安装命令：

RUN docker-php-ext-install pdo_mysql mysqli

3. 确保MariaDB完全就绪后再执行迁移 #

depends_on仅保证MariaDB容器先启动，但不确保数据库服务完全可用。可通过以下方式处理：

• 在执行migrate前添加延迟：

sleep 10 && php artisan migrate

• 为MariaDB容器添加健康检查，修改docker-compose.yml中mariadb服务配置：

mariadb:
    # ...其他配置
    healthcheck:
        test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
        timeout: 20s
        retries: 10

同时修改app服务的depends_on：

app:
    # ...其他配置
    depends_on:
        mariadb:
            condition: service_healthy

4. 确认数据库权限配置 #

检查MariaDB是否允许root用户从Laravel容器所在网络登录：
进入MariaDB容器执行：

docker exec -it mariadb mysql -u root

然后执行SQL：

SELECT user, host FROM mysql.user;

如果root用户的host不是%，执行以下命令授权：

GRANT ALL PRIVILEGES ON laravel.* TO 'root'@'%';
FLUSH PRIVILEGES;

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