告别环境配置噩梦：5分钟搭建Laravel开发环境的Docker Compose方案

原创 于 2024-08-15 09:26:28 发布 · 608 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

告别环境配置噩梦：5分钟搭建Laravel开发环境的Docker Compose方案

【免费下载链接】docker-compose-laravel A docker-compose workflow for local Laravel development 【免费下载链接】docker-compose-laravel 项目地址: https://gitcode.com/gh_mirrors/do/docker-compose-laravel

你是否也曾经历这些痛苦？

本地开发时，Laravel环境配置往往耗费数小时却仍遭遇各种问题：

  • 「端口被占用」错误频繁出现
  • 不同项目依赖的PHP版本冲突（5.6/7.4/8.1共存难题）
  • 团队成员间「在我电脑上能运行」的兼容性困境
  • MySQL/Redis版本差异导致的数据迁移失败
  • 邮件测试需配置真实SMTP服务器的繁琐流程

本文将带你使用Docker Compose实现5分钟内搭建生产级Laravel开发环境，全程无需手动安装PHP、Nginx、数据库，所有依赖一键启动，彻底解决「环境一致性」难题。

读完本文你将掌握：

  • ✅ 3条命令完成从克隆到运行的全流程
  • ✅ 8个核心服务的容器化配置原理
  • ✅ 权限问题/端口冲突等5类常见错误的解决方案
  • ✅ 数据持久化/HTTPS配置等进阶技巧
  • ✅ 开发环境无缝迁移至生产服务器的实战经验

为什么选择Docker Compose方案？

传统Laravel开发环境与容器化方案的核心差异对比：

维度传统开发环境Docker Compose方案
环境一致性依赖本地系统配置，易冲突容器隔离，团队成员环境100%一致
安装复杂度需要手动配置LAMP/LEMP栈一条命令自动拉取所有依赖
多版本兼容性需手动管理多PHP/MySQL版本容器标签指定版本，切换零成本
资源占用所有服务常驻内存按需启动，闲置服务可暂停
清理难度卸载易残留配置文件和依赖docker-compose down -v彻底清理
跨平台支持Windows/macOS/Linux差异大全平台一致体验
学习曲线需掌握各服务配置细节只需理解docker-compose.yml配置

核心架构解析：8个服务组件协同工作

本方案采用LEMP (Linux, Nginx, MySQL, PHP) 技术栈，通过Docker Compose编排以下服务：

mermaid

服务组件详细说明

服务名镜像/构建核心作用暴露端口数据卷挂载
appnginx:stable-alpine处理HTTP请求，反向代理PHP80:80./src:/var/www/html
php自定义PHP-FPM镜像执行Laravel代码，处理业务逻辑9000:9000./src:/var/www/html
mysqlmariadb:10.6关系型数据库，存储应用数据3306:3306可选：./mysql:/var/lib/mysql
redisredis:alpine缓存服务，提升应用性能6379:6379无
mailhogmailhog/mailhog本地邮件测试服务器，捕获发送邮件8025:8025无
composer基于php镜像管理PHP依赖包无./src:/var/www/html
npmnode:current-alpine管理前端依赖，编译静态资源3000-3001, 5173./src:/var/www/html
artisan基于php镜像执行Laravel命令行工具无./src:/var/www/html

快速上手：3步搭建开发环境

前置要求

确保系统已安装：

  • Docker Engine (20.10+)
  • Docker Compose (v2+)
  • Git

步骤1：克隆项目仓库

git clone https://gitcode.com/gh_mirrors/do/docker-compose-laravel.git
cd docker-compose-laravel

步骤2：启动容器网络

# 构建并启动核心服务
docker-compose up -d --build app

# 查看运行状态（应显示8个服务）
docker-compose ps

首次执行会自动从Docker镜像仓库拉取约1.2GB镜像，根据网络情况需3-10分钟。成功启动后终端显示：

   Name                  Command               State                    Ports                  
-------------------------------------------------------------------------------------------------
laravel_app_1        /docker-entrypoint.sh ngin ...   Up      0.0.0.0:80->80/tcp,:::80->80/tcp   
laravel_artisan_1    php /var/www/html/artisan        Exit 0                                     
laravel_composer_1   composer --ignore-platform-reqs   Exit 0                                     
laravel_mailhog_1    MailHog                          Up      0.0.0.0:1025->1025/tcp,:::1025->1025/tcp,
                                                              0.0.0.0:8025->8025/tcp,:::8025->8025/tcp
laravel_mysql_1      docker-entrypoint.sh mariadbd    Up      0.0.0.0:3306->3306/tcp,:::3306->3306/tcp
laravel_npm_1        npm                              Exit 0                                     
laravel_php_1        php-fpm -y /usr/local/etc/p ...   Up      0.0.0.0:9000->9000/tcp,:::9000->9000/tcp
laravel_redis_1      docker-entrypoint.sh redis ...   Up      0.0.0.0:6379->6379/tcp,:::6379->6379/tcp

步骤3：初始化Laravel项目

# 通过Composer安装最新版Laravel
docker-compose run --rm composer create-project laravel/laravel .

# 生成应用密钥
docker-compose run --rm artisan key:generate

# 配置环境变量（数据库连接）
cat > src/.env << EOF
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret
EOF

# 运行数据库迁移
docker-compose run --rm artisan migrate

现在访问 http://localhost 即可看到Laravel欢迎页面，邮件测试可通过 http://localhost:8025 访问MailHog控制台。

核心服务配置深度解析

Nginx服务 (app)

Nginx配置位于 dockerfiles/nginx/default.conf，核心配置片段：

server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;
    
    index index.php index.html;
    
    location / {
        try_files \$uri \$uri/ /index.php?\$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass php:9000;  # 连接php服务容器
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
        include fastcgi_params;
    }
}

关键特性：

  • PHP请求通过fastcgi_pass php:9000转发到php服务
  • Laravel友好的URL重写规则（支持路由美化）
  • 基于Alpine镜像，体积仅22MB（比官方Ubuntu镜像小80%）

PHP服务配置

PHP容器基于 php:8-fpm-alpine 构建，通过 dockerfiles/php.dockerfile 定制：

# 安装核心扩展
RUN docker-php-ext-install pdo pdo_mysql

# 编译安装Redis扩展
RUN mkdir -p /usr/src/php/ext/redis \
    && curl -L https://github.com/phpredis/phpredis/archive/5.3.4.tar.gz | tar xvz -C /usr/src/php/ext/redis --strip 1 \
    && docker-php-ext-install redis
    
# 配置运行用户
RUN addgroup -g ${GID} --system laravel
RUN adduser -G laravel --system -D -s /bin/sh -u ${UID} laravel
RUN sed -i "s/user = www-data/user = laravel/g" /usr/local/etc/php-fpm.d/www.conf

已预装扩展：

  • pdo_mysql (Laravel数据库必需)
  • redis (缓存/队列支持)
  • 兼容Laravel 8.x/9.x/10.x所有版本

数据库服务 (MySQL/MariaDB)

默认使用MariaDB 10.6（MySQL分支），环境变量配置：

environment:
  MYSQL_DATABASE: homestead
  MYSQL_USER: homestead
  MYSQL_PASSWORD: secret
  MYSQL_ROOT_PASSWORD: secret

连接信息：

  • 主机名：mysql（Docker内部服务发现）
  • 端口：3306
  • 默认数据库：homestead
  • 用户名/密码：homestead/secret

开发效率提升工具链

1. 一键执行Composer命令

无需本地安装Composer，直接通过容器运行：

# 安装依赖
docker-compose run --rm composer install

# 更新依赖
docker-compose run --rm composer update

# 安装特定包
docker-compose run --rm composer require guzzlehttp/guzzle

2. 前端资源编译

支持Laravel Mix和Vite两种构建工具：

# 安装npm依赖
docker-compose run --rm npm install

# 开发模式（带热更新）
docker-compose run --rm --service-ports npm run dev

# 生产环境构建
docker-compose run --rm npm run build

热更新配置：需在package.json中添加--host 0.0.0.0：

"scripts": {
  "dev": "vite --host 0.0.0.0",
  "build": "vite build"
}

3. Artisan命令集成

所有Laravel命令通过容器执行：

# 生成模型和迁移文件
docker-compose run --rm artisan make:model Post -m

# 运行队列 worker
docker-compose run --rm artisan queue:work

# 清除缓存
docker-compose run --rm artisan cache:clear

4. 邮件测试工具 (MailHog)

无需配置真实SMTP服务器，所有邮件自动捕获：

// .env配置
MAIL_MAILER=smtp
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

访问 http://localhost:8025 查看邮件队列，支持邮件内容预览和原始数据查看。

进阶配置：从开发到生产的无缝过渡

数据持久化方案

默认配置下，MySQL数据存储在容器内部，容器删除后数据丢失。生产环境必须配置数据卷：

  1. 创建数据目录：
mkdir -p ./mysql
  1. 修改docker-compose.yml的mysql服务：
mysql:
  image: mariadb:10.6
  volumes:
    - ./mysql:/var/lib/mysql  # 添加此行

权限问题终极解决方案

场景：Linux/macOS用户可能遇到文件读写权限错误。

方案1：非root用户环境（推荐）
# 导出当前用户ID和组ID
export UID=$(id -u)
export GID=$(id -g)

# 重建镜像
docker-compose build --no-cache
方案2：root用户环境（不推荐）

修改docker-compose.yml，将所有php.dockerfile替换为php.root.dockerfile：

php:
  build:
    context: ./dockerfiles
    dockerfile: php.root.dockerfile  # 修改此行

HTTPS配置（生产环境必需）

  1. 添加SSL证书存储目录：
mkdir -p ./dockerfiles/nginx/ssl
  1. 修改Nginx配置（dockerfiles/nginx/default.conf）：
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    
    # 其他配置同上...
}
  1. 使用Let's Encrypt获取免费证书：
# 启动临时容器获取证书
docker run --rm -v $(pwd)/dockerfiles/nginx/ssl:/etc/letsencrypt \
    certbot/certbot certonly --standalone -d your-domain.com

常见问题与解决方案（FAQ）

错误现象可能原因解决方案
访问localhost显示403 Forbidden代码目录权限不足执行export UID=$(id -u) GID=$(id -g) && docker-compose build --no-cache
MySQL连接失败 (10061错误)mysql服务未启动检查docker-compose ps确保mysql状态为Up，查看日志：docker-compose logs mysql
端口80/3306已被占用本地服务占用端口停止本地Nginx/MySQL服务，或修改docker-compose.yml中的端口映射如8080:80
Composer安装慢/失败网络问题添加国内镜像：docker-compose run --rm composer config -g repo.packagist composer https://packagist.phpcomposer.com
npm install卡在node-sass网络或Node版本问题使用淘宝镜像：docker-compose run --rm npm config set registry https://registry.npm.taobao.org

生产环境部署 checklist

部署到生产服务器前必须完成的10项检查：

  1. ✅ 修改.env文件：APP_ENV=production、APP_DEBUG=false
  2. ✅ 配置强随机数APP_KEY：docker-compose run --rm artisan key:generate
  3. ✅ 设置数据库密码为复杂密码，避免使用默认的secret
  4. ✅ 启用HTTPS并配置SSL证书自动续期
  5. ✅ 配置数据卷持久化所有重要数据
  6. ✅ 设置适当的文件权限：chmod -R 755 src/storage src/bootstrap/cache
  7. ✅ 禁用XDebug等开发工具扩展
  8. ✅ 配置日志轮转防止磁盘空间耗尽
  9. ✅ 设置定期数据库备份任务
  10. ✅ 限制容器资源使用（CPU/内存）防止DoS

总结：容器化开发的8大优势

  1. 环境一致性：开发/测试/生产环境完全一致，消除"在我电脑上能运行"问题
  2. 安装零配置：新人入职5分钟即可完成开发环境搭建
  3. 资源隔离：不同项目使用独立容器，避免依赖冲突
  4. 快速重建：环境损坏时10分钟内可完全重建
  5. 跨平台兼容：完美支持Windows/macOS/Linux开发环境
  6. 学习成本低：无需深入学习各服务底层配置
  7. 版本控制友好：配置文件纳入Git管理，环境变更可追溯
  8. CI/CD无缝集成：容器化配置可直接用于自动化部署流程

下一步行动计划

  1. 立即克隆项目体验：git clone https://gitcode.com/gh_mirrors/do/docker-compose-laravel.git
  2. 尝试将现有Laravel项目迁移到容器环境
  3. 探索添加Elasticsearch/Meilisearch等扩展服务
  4. 配置Git hooks实现提交前自动运行测试

收藏本文，下次搭建Laravel环境直接取用！关注作者获取更多Docker容器化实战教程，下期将推出《Laravel容器化生产环境性能优化指南》。

附录：常用命令速查表

功能命令
启动所有服务docker-compose up -d
构建并启动服务docker-compose up -d --build
查看运行状态docker-compose ps
查看服务日志docker-compose logs -f app
停止所有服务docker-compose down
停止并删除数据卷docker-compose down -v
执行Artisan命令docker-compose run --rm artisan [命令]
执行Composer命令docker-compose run --rm composer [命令]
执行npm命令docker-compose run --rm npm [命令]
进入PHP容器docker-compose exec php sh
数据库备份docker-compose exec mysql mysqldump -u homestead -psecret homestead > backup.sql

【免费下载链接】docker-compose-laravel A docker-compose workflow for local Laravel development 【免费下载链接】docker-compose-laravel 项目地址: https://gitcode.com/gh_mirrors/do/docker-compose-laravel

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值