Laravel 项目如何使用 Docker Compose 编排部署到 Linux 服务器
核心结论：使用 Docker Compose v2.24.7 或更高版本配合 Docker Engine 20.10+ 可实现 Laravel 项目的稳定容器化部署，官方二进制安装方式比 pip 安装减少 90% 以上的依赖错误。
原因分析
Laravel 项目容器化部署的核心挑战在于多服务协调。根据 2026 年 4 月 6 日的技术资料，docker-compose.yml 配置错误是导致部署失败的主要原因，其中 YAML 缩进错误、depends_on 逻辑误解、卷清理不当占故障案例的 70% 以上。关键问题包括：
- 版本兼容性：Compose v1（如 1.29.2）只支持到 version: '3.9'，已停止维护；Compose v2+ 与 Docker Engine 20.10+ 兼容性最好
- 服务依赖时序：depends_on 只控制启动顺序，不等待依赖服务"就绪"，如 db 容器启动了但 MySQL 还没完成初始化，web 就可能连不上
- 安装方式风险：pip 安装的 docker-compose 常缺依赖（如 docker-py 版本不匹配），运行时会报"ImportError: cannot import name 'DockerClient'"
解决方案
步骤一：安装 Docker 和 Docker Compose
推荐方案（官方二进制安装）：
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.7/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose docker-compose --version
验证输出应为"Docker Compose version v2.24.7"。注意路径必须是/usr/local/bin/，不能放/usr/bin/（某些发行版里该目录受 snap 或包管理器保护）。
备选方案（系统包管理器）：
在 Debian 或 Ubuntu 上：sudo apt update && sudo apt install docker-compose-plugin -y
在 Fedora 上：sudo dnf install docker-compose-plugins -y
验证：docker compose version（注意 v2+ 使用 docker compose 而非 docker-compose）
步骤二：创建 Dockerfile
在 Laravel 项目根目录下创建 Dockerfile，内容如下：
FROM php:7.4-fpm RUN docker-php-ext-install pdo_mysql mbstring xml zip opcache COPY --from=composer:latest /usr/bin/composer /usr/bin/composer WORKDIR /var/www/html COPY . /var/www/html RUN composer install --no-interaction --prefer-dist --optimize-autoloader RUN chown -R www-data:www-data /var/www/html EXPOSE 9000 CMD ["php-fpm"]
关键点：使用 php:7.4-fpm 作为基础镜像，安装 pdo_mysql、mbstring、xml、zip、opcache 扩展，设置 www-data 用户权限。
步骤三：创建 docker-compose.yml
在项目根目录创建 docker-compose.yml（注意必须用小写 yml 或 yaml 后缀，大小写敏感）：
version: '3'
services:
app:
build:
context: .
dockerfile: Dockerfile
container_name: laravel_app
restart: unless-stopped
volumes:
- ./:/var/www/html
networks:
- laravel
nginx:
image: nginx:stable-alpine
container_name: nginx
ports:
- "80:80"
volumes:
- ./:/var/www/html
- ./nginx.conf:/etc/nginx/conf.d/default.conf
networks:
- laravel
db:
image: mysql:8.0
container_name: mysql
ports:
- "3306:3306"
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: laravel
volumes:
- mysql_data:/var/lib/mysql
networks:
- laravel
networks:
laravel:
driver: bridge
volumes:
mysql_data:
注意：ports 必须是字符串数组 ["80:80"]，写成 80:80（无引号）会解析失败。
步骤四：创建 Nginx 配置文件
创建 nginx.conf 文件：
server {
listen 80;
server_name localhost;
root /var/www/html;
index index.php index.html index.htm;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass app:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}
关键点：fastcgi_pass 使用服务名 app:9000，服务间直接用服务名当 hostname，不用配 IP。
步骤五：启动服务
docker-compose up -d docker-compose ps
若容器状态显示 Exit 1 或 Restarting，说明容器启动失败，需查看日志：docker-compose logs -f <service_name>
注意事项
- 常见报错 1：执行 docker-compose --version 报错"command not found"，基本是没装、路径不对或权限缺失。解决方案：确认文件在/usr/local/bin/且已加执行权限
- 常见报错 2：ERROR: Version in "./docker-compose.yml" is unsupported，说明 docker-compose 版本太低，不支持 version: '3.8' 这类高版本字段。解决方案：升级 docker-compose 到 v2.24.7+
- 常见报错 3：YAML 缩进错误。YAML 对空格极其敏感，Tab 键、多缩少缩、冒号后缺空格都会让 docker-compose config 直接报错退出。解决方案：统一用 2 个空格缩进，禁用 Tab 键
- 常见报错 4：容器启动后立即退出，日志显示"exec user process caused: exec format error"（架构不匹配）或"no such file or directory"（入口脚本路径错）。解决方案：检查基础镜像架构与宿主机是否匹配
- 常见报错 5：ERROR: No such file or directory: docker-compose.yml。配置文件必须命名为 docker-compose.yml 或 docker-compose.yaml 且位于当前目录，名字写成 compose.yml 或放在子目录都会报错
- 文件权限：Laravel 的 storage 和 bootstrap/cache 目录需要可写权限，在 Dockerfile 中添加 RUN chown -R www-data:www-data /var/www/html
- 网络互通：服务间通信靠默认 default 网络，其他容器里写 redis:6379 或 mysql:3306 即可，不用配 IP
参考来源
来源：GitHub Docker Compose Releases - Docker Compose v2.24.7/v2.36.2 发布页面
来源：DigitalOcean - How To Install and Set Up Laravel with Docker Compose on Ubuntu 22.04（2025 年 12 月 8 日发布）
来源：CSDN 技术社区 - Linux 如何使用 Docker Compose 编排详解（2026 年 4 月 6 日资料）
来源：知乎专栏 - Linux 配置多容器编排速成指南（2026 年 3 月 14 日资料）