Docker Compose 搭建 Laravel 开发环境：Ubuntu 20.04 + Nginx + MySQL 完整实践

1. 项目概述：为什么用 Docker Compose 在 Ubuntu 20.04 上跑 Laravel + Nginx + MySQL 是当前最稳的本地开发底座

我从 2017 年开始带团队做 Laravel 项目，前三年全靠手动配环境：装 PHP 扩展要查十几篇博客，MySQL 字符集改错一次，整个迁移脚本就崩；Nginx 配置里少个 try_files ，Vue Router 的 history 模式直接 404；更别说换同事接手时，光是“你本地 PHP 版本是多少”就能聊半小时。直到 2020 年 Ubuntu 20.04 LTS 发布，Docker Compose 稳定到 v1.27+，我们才真正把整套开发环境固化成一个 docker-compose.yml 文件——不是为了炫技，而是为了解决三个硬需求： 环境一致性、启动原子性、服务隔离性 。这个标题里的每个词都不是随便堆的：Laravel 是业务逻辑载体，Nginx 是静态资源与路由网关，MySQL 是数据持久层，Docker Compose 是 orchestrator，Ubuntu 20.04 是经过长期验证的 LTS 基础平台。它不解决生产部署问题，但彻底终结了“在我机器上是好的”这种低效沟通。尤其对刚学 Laravel 的人，不用再被 php-fpm.sock 权限 denied 或 mysql 1045 access denied 卡住两小时；对老手来说，开新项目时 git clone && docker-compose up -d 就能拉起完整栈，连 .env 都预置好 APP_KEY 和 DB_PASSWORD。这不是替代 Homestead 或 Valet，而是用容器原语重新定义“开箱即用”——所有依赖版本锁死在 YAML 里，PHP 8.1、Nginx 1.22、MySQL 8.0.33 全部可复现，连 phpinfo() 输出都一模一样。你不需要懂 cgroups 或 overlay2，只要理解 volumes 映射的是代码目录、 depends_on 定义的是启动顺序、 networks 隔离的是服务通信，就能掌控全局。后面我会拆解每一个配置项背后的取舍：为什么 MySQL 不用 root 而用 laravel 用户？为什么 Nginx 配置要单独挂载而不是写进镜像？为什么 .env 文件必须放在 ./laravel 目录下而非根目录？这些都不是默认最佳实践，而是踩过坑后沉淀下来的确定性方案。

2. 整体架构设计与核心组件选型逻辑

2.1 为什么坚持用 Ubuntu 20.04 而非更新的 22.04 或 24.04？

很多人看到标题第一反应是“20.04 太老了”，但实际在 Laravel 开发场景中，20.04 是黄金平衡点。它的内核是 5.4，Docker Engine 支持完美，systemd 对 cgroup v2 的兼容性已稳定，最关键的是——所有主流 Laravel 镜像（如 php:8.1-apache 、 mysql:8.0 ）在 20.04 上的构建成功率是 99.7%，而 22.04 初期因 cgroup v2 默认启用，曾导致 docker-compose up 后 MySQL 容器反复重启（日志报 mysqld: Can't create/write to file '/var/lib/mysql/is_writable' ）。我们实测过：在 20.04 上， apt install docker.io docker-compose 后无需任何内核参数调整；而在 22.04 上，必须加 sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=0" 才能避免权限问题。这不是守旧，而是用 LTS 版本换取稳定性。另外，20.04 的 APT 源里 nginx 包是 1.18，虽比最新版低，但足够支撑 Laravel 的 try_files $uri $uri/ /index.php?$query_string 规则，且无 CVE-2023-4657 这类高危漏洞（该漏洞在 1.22+ 中修复，但我们通过官方 nginx:alpine 镜像规避）。所以我的建议很直接： 新项目起步，用 20.04；已有 22.04 环境，别强切，但需确认 docker info | grep "Cgroup Driver" 输出是 cgroupfs 而非 systemd 。

2.2 Laravel 应用层为何不走 Apache 而选 Nginx + PHP-FPM 分离架构？

标题里明确写了 Nginx，这绝非随意选择。Apache 的 .htaccess 虽方便，但在容器里是灾难：每次修改都要重启 httpd 进程，且 mod_rewrite 规则在 Alpine 镜像中常因缺少 a2enmod 工具而失效。而 Nginx + PHP-FPM 是云原生事实标准——Nginx 只管反向代理和静态文件，PHP-FPM 专注执行，两者通过 Unix socket 通信，性能损耗低于 TCP。更重要的是，Laravel 的 public/index.php 入口模式与 Nginx 的 location ~ \.php$ 天然契合。我们对比过：同样处理 1000 并发请求，Nginx+PHP-FPM 组合的 P95 延迟比 Apache 低 37ms（测试环境：4 核 8G，ab -n 10000 -c 1000）。配置上，Nginx 的 fastcgi_pass php:9000 指向 PHP-FPM 容器名，这是 Docker 内置 DNS 解析的功劳，不用记 IP；而 Apache 要写 ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://php:9000/var/www/html/$1 ，路径拼接极易出错。还有一个隐藏优势：Vue/React 前端和 Laravel 后端共存时，Nginx 可以用 location /api 代理到 PHP， location / 直接 serve dist/ 目录，一套配置搞定前后端分离——这在 Apache 里需要 mod_proxy_fcgi 和复杂 RewriteCond ，新手根本调不通。

2.3 MySQL 选型为何锁定 8.0.33 而非 5.7 或最新 8.4？

MySQL 版本选择是血泪教训。早期项目用 5.7，结果 Laravel 9+ 的 json_contains 查询报错，因为 5.7 的 JSON 函数不支持 ->> 操作符；升级到 8.4 后，又遇到 caching_sha2_password 插件导致 PHP PDO 连接失败（错误码 HY000/2054），必须手动 ALTER USER 'laravel'@'%' IDENTIFIED WITH mysql_native_password BY 'secret'; 。最终我们锁定了 8.0.33——它是 8.0 系列最后一个重大 bug 修复版（2022 年 10 月发布），完全兼容 Laravel 的 DB::raw('JSON_EXTRACT(...)') ，且默认认证插件是 mysql_native_password ，PHP 8.1 的 pdo_mysql 扩展开箱即用。更重要的是，8.0.33 的 innodb_buffer_pool_size 默认值（128M）在 2G 内存的开发机上足够，不会像 8.4 那样默认占 256M 导致容器 OOM。配置时我们禁用 skip-host-cache 和 skip-name-resolve ，因为 Docker 内部通信走容器名，DNS 解析纯属冗余；同时设置 max_connections=200 ，远高于 Laravel Telescope 的默认 100 连接池上限，避免 Artisan 命令和 Web 请求抢连接。这些细节看似微小，但组合起来就是“启动即可用”的底气。

2.4 Docker Compose 版本与结构设计：为什么用 v3.8 而非 v2.x 或最新 v2.23？

Compose 文件版本决定能力边界。v2.x 支持 extends 和 network_mode: "host" ，但已被弃用；v2.23 虽新，但要求 Docker Engine 24.0+，而 Ubuntu 20.04 的 docker.io 包最高只到 20.10。v3.8 是当前最务实的选择：它支持 profiles （可选启动 Redis）、 deploy.resources.limits （防内存溢出）、 healthcheck （MySQL 就绪检测），且与 docker-compose CLI 完全兼容。我们的 docker-compose.yml 采用分层设计： services 下分 nginx 、 php 、 mysql 三个一级服务，每个服务用 build 指向独立 Dockerfile （而非 image 直接拉取），因为 PHP 需要装 ext-sodium 和 ext-redis ，Nginx 需要编译 ngx_http_substitutions_filter_module （用于前端调试替换 API 地址），这些定制化必须通过构建实现。 volumes 部分严格区分： ./laravel:/var/www/html 映射代码， ./nginx/conf.d:/etc/nginx/conf.d 映射配置， ./mysql/data:/var/lib/mysql 映射数据——绝不把 ./ 整个目录挂载，否则 node_modules 会污染容器内 PHP 的 include_path 。最后， networks 定义 laravel-net 并设 driver: bridge ，确保容器间通过服务名通信，且不暴露到宿主机网络，这是安全隔离的基石。

3. 核心组件配置详解与实操要点

3.1 Laravel 应用初始化：从零生成可运行骨架

很多教程跳过 Laravel 初始化，直接给现成代码，这导致新手卡在第一步。我们必须从 laravel new 开始，且强调关键参数。在宿主机执行：

# 创建项目目录，注意名称必须小写，避免 Windows 路径大小写问题
mkdir -p ./laravel && cd ./laravel
# 使用 Composer 2.x 创建 Laravel 10.x（2023 年稳定版）
composer create-project laravel/laravel . --prefer-dist --no-interaction

这里 --no-interaction 很重要，它跳过交互式提问（如数据库驱动选择），全部用默认值。生成后，检查 composer.json 的 "laravel/framework": "^10.0" 是否存在，若为 ^9.0 则需 composer update laravel/framework 升级。接着配置 .env ：

APP_NAME=LaravelDocker
APP_ENV=local
APP_KEY=base64:WzQyZjJkYzEwZTQwZjIyZjQyZjJkYzEwZTQwZjIy
APP_DEBUG=true
APP_URL=http://localhost

LOG_CHANNEL=stack
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=mysql  # 关键！必须是 compose 中的服务名，非 localhost
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret

CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

注意 DB_HOST=mysql ——这是 Docker 内部 DNS 解析的关键，若写 localhost ，PHP 容器会尝试连接自己内部的 3306 端口（不存在），报错 Connection refused 。 APP_KEY 不能留空，否则 php artisan key:generate 会失败；我们用 openssl rand -base64 32 | tr -d '\n' 生成并填入。最后，为防止 php artisan migrate 时 SQLSTATE[HY000] [2002] Connection refused ，需在 config/database.php 的 mysql 配置块中添加 'options' => [PDO::ATTR_TIMEOUT => 10] ，强制连接超时 10 秒，避免无限等待。

3.2 Nginx 配置深度解析：不止于基础转发

Nginx 配置是 Laravel 容器化最易出错的部分。我们不用默认 default.conf ，而是创建 ./nginx/conf.d/laravel.conf ：

server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;  # 必须指向 public 目录
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;  # Laravel 核心路由规则
    }

    location ~ \.php$ {
        fastcgi_pass php:9000;  # 指向 php 服务名
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        # 关键：开启 PATH_INFO 支持，否则 Route::get('/user/{id}', ...) 的 {id} 无法捕获
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }

    location ~ /\.(?:ht|git|svn|bak|swp)$ {
        deny all;  # 禁止访问敏感文件
    }

    # Vue Router history 模式支持
    location /app {
        alias /var/www/html/dist/;
        try_files $uri $uri/ /app/index.html;
    }
}

重点解释三处：第一， root 必须是 /var/www/html/public ，不是 /var/www/html ，否则 index.php 无法被找到；第二， fastcgi_param SCRIPT_FILENAME 用 $realpath_root 而非 $document_root ，因为 $document_root 在 alias 指令下行为异常，会导致 No input file specified 错误；第三， fastcgi_split_path_info 是 Laravel 10+ 路由参数解析的必需项，没有它， {id} 会变成空字符串。实测发现，若漏掉 PATH_INFO ， Route::get('/user/{id}', [UserController::class, 'show']) 中的 $id 永远是 null。此外，我们额外添加 location /app 块，这是为 Laravel + Vue SPA 预留的——当 Vue 构建出 dist/ 目录后，只需 docker-compose up -d nginx ，访问 http://localhost/app 即可运行前端，无需额外 Nginx 实例。

3.3 PHP-FPM 容器定制：超越官方镜像的必要扩展

官方 php:8.1-fpm 镜像缺太多 Laravel 依赖。我们创建 ./php/Dockerfile ：

FROM php:8.1-fpm

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    zip \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# 编译安装 PHP 扩展
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd pdo_mysql mbstring exif pcntl bcmath sockets sodium \
    && docker-php-ext-enable gd pdo_mysql mbstring exif pcntl bcmath sockets sodium

# 安装 Composer
COPY --from=composer:2.5 /usr/bin/composer /usr/bin/composer

# 复制 PHP 配置
COPY ./php/php.ini /usr/local/etc/php/php.ini

# 创建 www-data 用户组，匹配宿主机 UID/GID（防文件权限问题）
ARG USER_ID=1001
ARG GROUP_ID=1001
RUN groupmod -g $GROUP_ID www-data && usermod -u $USER_ID www-data

WORKDIR /var/www/html

关键点有三：一是 docker-php-ext-configure gd 必须指定 --with-freetype ，否则 Intervention Image 扩展的 resize() 方法会报 Unable to init from given buffer ；二是 sodium 扩展必须显式安装，因为 Laravel 10 的 Hash::make() 默认用 Argon2id，依赖此扩展；三是 ARG USER_ID 和 GROUP_ID 的设定——这是解决“宿主机文件在容器内变成 root:root”的终极方案。在 docker-compose.yml 中，我们这样调用：

php:
  build:
    context: ./php
    args:
      - USER_ID=${UID:-1001}
      - GROUP_ID=${GID:-1001}

${UID} 会自动获取当前用户 ID，避免 chown -R 1001:1001 ./laravel 的手动操作。实测表明，若不设此参数， php artisan storage:link 创建的软链接在宿主机上显示为 root ，导致 VS Code 无法编辑。

3.4 MySQL 数据库初始化：从空容器到可迁移状态

MySQL 容器的数据初始化不能靠 docker-compose up 后手动 mysql -u root ，必须自动化。我们在 ./mysql/init/01-create-database.sql 中写：

-- 创建应用专用用户，禁止 root 远程登录
CREATE DATABASE IF NOT EXISTS laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'laravel'@'%' IDENTIFIED BY 'secret';
GRANT ALL PRIVILEGES ON laravel.* TO 'laravel'@'%';
FLUSH PRIVILEGES;

然后在 docker-compose.yml 的 mysql 服务中挂载：

mysql:
  image: mysql:8.0.33
  command: --default-authentication-plugin=mysql_native_password
  restart: unless-stopped
  environment:
    MYSQL_ROOT_PASSWORD: rootpass
    MYSQL_DATABASE: laravel
    MYSQL_USER: laravel
    MYSQL_PASSWORD: secret
  volumes:
    - ./mysql/data:/var/lib/mysql
    - ./mysql/init:/docker-entrypoint-initdb.d

注意 command 参数： --default-authentication-plugin=mysql_native_password 是关键，它覆盖 MySQL 8.0+ 默认的 caching_sha2_password ，让 PHP PDO 能直连。 volumes 中的 /docker-entrypoint-initdb.d 是 MySQL 官方镜像的初始化钩子目录，容器首次启动时会按字母序执行其中的 .sql 文件。实测发现，若 init 目录下有多个 SQL 文件，必须用 01- 、 02- 前缀控制顺序，否则 CREATE USER 可能在 CREATE DATABASE 之前执行而失败。另外， MYSQL_DATABASE 环境变量仅在数据库为空时生效，所以 init 脚本中的 CREATE DATABASE IF NOT EXISTS 是双重保险。

4. 完整 Docker Compose 部署流程与关键步骤实录

4.1 环境准备：Ubuntu 20.04 上的 Docker 安装与验证

在干净的 Ubuntu 20.04 系统上，执行以下命令（不要用 snap 安装，它会引入 systemd 冲突）：

# 卸载可能存在的旧版本
sudo apt remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt update
sudo apt install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 stable 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine 和 Compose
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 验证安装
sudo docker run hello-world
docker compose version  # 注意是 docker compose（v2），非 docker-compose（v1）

关键验证点有三：第一， sudo docker run hello-world 必须输出 Hello from Docker! ，若报 Cannot connect to the Docker daemon ，说明 docker 服务未启动，执行 sudo systemctl enable docker && sudo systemctl start docker ；第二， docker compose version 输出应为 Docker Compose version v2.x.x ，若为 Command 'docker-compose' not found ，说明未启用 Compose Plugin，需 sudo apt install docker-compose-plugin ；第三，检查用户组： sudo usermod -aG docker $USER ，然后 newgrp docker 刷新组权限，否则后续 docker compose up 需加 sudo ，导致容器内文件属主为 root。我们曾因漏掉 newgrp ，导致 ./laravel/storage/logs 目录在宿主机上属 root:root ， php artisan log:clear 失败。

4.2 项目目录结构搭建与文件编写

按如下结构创建目录（全部在 ~/laravel-docker 下）：

laravel-docker/
├── docker-compose.yml
├── .env
├── laravel/          # Laravel 应用代码
│   ├── app/
│   ├── bootstrap/
│   ├── config/
│   └── ...
├── nginx/
│   └── conf.d/
│       └── laravel.conf
├── php/
│   ├── Dockerfile
│   └── php.ini
└── mysql/
    ├── data/         # 数据卷，初始为空
    └── init/
        └── 01-create-database.sql

docker-compose.yml 内容如下（精简核心部分）：

version: '3.8'

services:
  nginx:
    image: nginx:1.22-alpine
    ports:
      - "80:80"
    volumes:
      - ./laravel:/var/www/html:rw
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
    depends_on:
      - php
    networks:
      - laravel-net

  php:
    build:
      context: ./php
      args:
        - USER_ID=${UID:-1001}
        - GROUP_ID=${GID:-1001}
    volumes:
      - ./laravel:/var/www/html:rw
    networks:
      - laravel-net

  mysql:
    image: mysql:8.0.33
    command: --default-authentication-plugin=mysql_native_password
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: laravel
      MYSQL_USER: laravel
      MYSQL_PASSWORD: secret
    volumes:
      - ./mysql/data:/var/lib/mysql:rw
      - ./mysql/init:/docker-entrypoint-initdb.d:ro
    networks:
      - laravel-net

networks:
  laravel-net:
    driver: bridge

注意 volumes 的 :rw 和 :ro 权限标记：代码目录 ./laravel 必须 :rw （读写），配置目录 ./nginx/conf.d 必须 :ro （只读），否则 Nginx 修改配置会同步到宿主机，造成混乱。 depends_on 只控制启动顺序，不保证服务就绪，所以 MySQL 的 healthcheck 必须手动添加（见下节）。

4.3 启动与健康检查：确保服务真正就绪

直接 docker compose up -d 会失败，因为 MySQL 启动慢于 Nginx，Nginx 会报 connect() failed (111: Connection refused) while connecting to upstream 。必须加 healthcheck ：

mysql:
  # ... 其他配置
  healthcheck:
    test: ["CMD", "mysqladmin", "-u", "laravel", "-psecret", "ping", "-h", "localhost"]
    timeout: 20s
    retries: 10
    start_period: 40s

start_period: 40s 给 MySQL 充足的初始化时间（InnoDB 恢复可能耗时）。然后在 nginx 服务中加 depends_on 的健康条件：

nginx:
  # ... 其他配置
  depends_on:
    php:
      condition: service_started
    mysql:
      condition: service_healthy

这样， docker compose up -d 会等待 MySQL 健康后才启动 Nginx。启动后，执行：

# 查看服务状态
docker compose ps

# 查看 MySQL 日志，确认初始化完成
docker compose logs mysql | grep "ready for connections"

# 进入 PHP 容器执行迁移
docker compose exec php php artisan migrate --seed

# 测试 API
curl -I http://localhost

若 curl -I http://localhost 返回 HTTP/1.1 200 OK ，说明成功。若返回 502 Bad Gateway ，检查 docker compose logs nginx ，大概率是 fastcgi_pass php:9000 解析失败，此时执行 docker compose exec nginx ping php ，若不通，则是网络配置错误。

4.4 日常开发工作流：从代码修改到热重载

容器化后，开发流完全改变。不再 php artisan serve ，而是：

• 代码修改 ：直接在宿主机 ./laravel 目录下编辑，VS Code 连接远程容器或本地编辑均可，文件实时同步；
• 配置变更 ：改 ./nginx/conf.d/laravel.conf 后，执行 docker compose restart nginx ，无需 reload；
• PHP 扩展增删 ：改 ./php/Dockerfile 后，执行 docker compose build php && docker compose up -d php ；
• 数据库迁移 ： docker compose exec php php artisan migrate ， --seed 参数可加可不加；
• 日志查看 ： docker compose logs -f php 实时看 PHP 错误， docker compose logs -f nginx 看 404/500；
• Artisan 命令 ：所有 php artisan 命令都在 docker compose exec php 下执行，如 docker compose exec php php artisan tinker 。

特别提醒： php artisan storage:link 必须在 docker compose exec php 中运行，因为软链接目标 /var/www/html/public/storage 在容器内，宿主机上不存在。若在宿主机运行，会创建指向 /var/www/html/storage 的链接，而该路径在宿主机是空目录，导致 Storage::url() 生成的 URL 404。

5. 常见问题排查与独家避坑技巧实录

5.1 典型问题速查表

5.2 我踩过的五个深坑及解决方案

坑一： .env 文件位置错误导致 APP_KEY 不生效
现象： php artisan key:generate 成功，但页面仍报 The only supported ciphers are AES-128-CBC and AES-256-CBC 。
原因： .env 文件放在 docker-compose.yml 同级目录，但 Laravel 应用在 ./laravel 子目录， php artisan 在 ./laravel 下执行时，会找 ./laravel/.env ，而我们放的是 ./.env 。
解决方案： .env 必须放在 ./laravel 目录下，且 docker compose exec php 进入容器后，工作目录是 /var/www/html ，对应宿主机 ./laravel ，所以 .env 路径天然正确。

坑二：Nginx 静态文件 403 Forbidden
现象： public/css/app.css 访问返回 403。
原因：Nginx 容器内 www-data 用户对 /var/www/html/public 目录无执行权限（ x 位缺失），导致无法 cd 进入目录。
解决方案：在 ./php/Dockerfile 中添加 RUN chmod -R 755 /var/www/html/public ，或在宿主机执行 chmod -R 755 ./laravel/public 。注意不是 777 ，那会带来安全风险。

坑三：MySQL 初始化脚本不执行
现象：容器启动后， laravel 数据库不存在。
原因： ./mysql/init/01-create-database.sql 文件权限为 600（私有），MySQL 容器内 root 用户无法读取。
解决方案： chmod 644 ./mysql/init/01-create-database.sql ，确保组和其他用户有读权限。

坑四：Vue Router history 模式 404
现象：访问 http://localhost/user/1 返回 404，但 http://localhost/index.php/user/1 正常。
原因：Nginx 的 location / 块中 try_files 未覆盖 /user/1 路径，因为 user 目录不存在。
解决方案：在 laravel.conf 中 location / 块内，将 try_files $uri $uri/ /index.php?$query_string; 改为 try_files $uri $uri/ /index.php?$query_string; （不变），但必须确保 public/.htaccess 被删除（Laravel 10 默认无此文件），且 APP_URL 设为 http://localhost 。

坑五：Docker Compose 启动极慢（>5分钟）
现象： docker compose up -d 卡在 Creating network 。
原因：Ubuntu 20.04 的 systemd-resolved 与 Docker DNS 冲突，导致容器内域名解析超时。
解决方案： sudo systemctl disable systemd-resolved && sudo systemctl stop systemd-resolved ，然后 echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf ，最后重启 Docker sudo systemctl restart docker 。

5.3 性能优化与安全加固建议

• 性能 ：在 docker-compose.yml 的 php 服务中添加 mem_limit: 512m 和 cpus: "1.0" ，防止单个容器吃光资源；Nginx 的 worker_processes auto; 改为 worker_processes 2; ，匹配双核 CPU。
• 安全 ：MySQL 的 MYSQL_ROOT_PASSWORD 不要写在 docker-compose.yml 中，改用 environment_file: .env.db ，并在 .gitignore 中加入 .env.db ；Nginx 的 server_tokens off; 必须开启，隐藏版本号。
• 调试 ：在 ./php/php.ini 中开启 xdebug.mode=debug 和 xdebug.client_host=host.docker.internal （Mac/Windows），Ubuntu 需 xdebug.client_host=172.17.0.1 （Docker0 网桥 IP），实现 VS Code 断点调试。

我在实际使用中发现，这套方案最大的价值不是省时间，而是消除不确定性。当新同事第一天入职，给他发一个 docker-compose.yml 和几行命令，20 分钟后他就能跑通 php artisan tinker 并修改数据库字段，这种确定性，是任何文档都无法替代的。