Laradock 使用指南:基于 Docker 的完整 PHP 开发环境搭建与配置详解

原创2026-09-22 17:43:08792 阅读
文章标签:后端开发工具DevOps

Laradock 使用指南:基于 Docker 的完整 PHP 开发环境搭建与配置详解

本文以 Laradock 官方中文文档(README-zh.md)为核心骨架,结合仓库内 docker-compose.yml、.env.example、laradock CLI 脚本及各服务目录下的真实配置(如 nginx/defaults.env、mysql/defaults.env)进行纵深扩充,帮助你从零开始用 Docker 搭建一套完整、可复用的 PHP 本地开发环境,并理解其底层实现原理。

Laradock 是一套基于 Docker 的完整 PHP 开发环境:仓库内预配置了 PHP 应用所需的一切容器(Nginx、PHP-FPM、MySQL、PostgreSQL、Redis 等),克隆后执行一条命令即可启动整套本地开发栈。本文将从快速开始讲起,逐步深入到 .env 配置、Compose 架构与 Workspace 开发终端,让你既能"先用 Docker",也能"后学习 Docker"。

概述:为什么用 Laradock

Laradock 的口号是"先用 Docker,后学习 Docker"——它把 PHP 项目的第一天(通常花在环境搭建上)省掉:克隆一次、运行一条命令,整套环境即刻就绪。

它的核心定位是:

  • 开箱即用:提供 PHP 应用所需的一切预配置容器(Nginx、PHP-FPM、MySQL、PostgreSQL、Redis 等等),无需任何手动配置;
  • 适用于任何 PHP 项目:Laravel、Symfony、WordPress、Drupal、Magento 乃至原生 PHP 都可以运行;
  • 跨平台一致:在 Linux、macOS 和 Windows 上提供完全一致的开发环境。

从仓库结构看,每个服务都是一个独立的目录,包含 compose.yml(服务定义)、Dockerfile(镜像构建)、defaults.env(该服务的默认配置),例如 nginx/compose.yml 与 mysql/compose.yml,模块化程度非常高。

环境要求

开始之前,请确保本机已经安装:

工具 说明
Docker 使用了 Compose 的 include 特性,旧版 v1 无法解析)
Git 用于克隆 Laradock 仓库

从 laradock CLI 脚本的 check_docker 逻辑可以看到,启动时会校验三件事:Docker 是否安装、Docker daemon 是否在运行、Compose 是否为 v2.20+(MIN_COMPOSE_MINOR=20)。因此使用旧版 docker-compose v1 直接运行会报错,请更新到最新版 Docker。

快速开始:五分钟跑起 PHP + Nginx + MySQL + Redis

第一步:克隆 Laradock 到你的 PHP 项目

git clone https://github.com/Laradock/laradock.git

建议把 Laradock 克隆到你的 PHP 项目目录内部(例如项目根目录下的 laradock/ 子目录),这样代码路径的挂载配置最省事。

第二步:生成 .env 配置文件

cd laradock
cp .env.example .env

.env 是整个环境的总开关。仓库根目录的 .env.example 顶部有一段重要的配置机制说明,值得先读懂:

  1. 将 .env.example 复制为 .env,它保存所有服务共享的配置(路径、PHP 版本、项目名);
  2. 每个服务还自带一份已填好默认值的配置:mysql/defaults.env、nginx/defaults.env 等,你不需要复制或编辑这些文件;
  3. 想改任何配置(共享或单服务的),在 .env 里写一行即可覆盖——.env 永远优先于 defaults.env。例如在 .env 加一行 MYSQL_PORT=3307 就能覆盖默认端口。

从旧版升级?继续使用你现有的完整 .env 即可,所有旧配置项依然按原方式生效。

第三步:启动容器

docker compose up -d workspace nginx mysql redis

这条命令启动四个容器:workspace(一体化开发终端)、nginx(Web 服务器)、mysql(数据库)、redis(缓存)。参数 -d 表示后台运行。

从仓库源码看,这套组合的联动关系如下:

  • nginx/compose.yml 将宿主机代码目录 ${APP_CODE_PATH_HOST} 挂载到容器内 ${APP_CODE_PATH_CONTAINER}(默认 /var/www),并把 80/443 端口映射到宿主机,depends_on 声明依赖 php-fpm,通过 FastCGI 将请求转发给 PHP-FPM 容器;
  • mysql/compose.yml 将数据持久化到 ${DATA_PATH_HOST}/mysql,并通过 docker-entrypoint-initdb.d 目录支持启动时自动执行初始化 SQL 脚本(仓库中提供了 createdb.sql.example 示例);
  • workspace 则提供了完整的命令行开发环境(详见下文"Workspace 详解")。

第四步:配置项目连接数据库与缓存

打开你自己项目的 .env 文件(注意:不是 Laradock 的 .env),设置:

DB_HOST=mysql
REDIS_HOST=redis
QUEUE_HOST=beanstalkd

这里的主机名 mysql、redis 正是 Compose 网络中的容器服务名——Laradock 各服务都接入统一的 Docker 网络(docker-compose.yml 定义了 frontend 与 backend 两张 bridge 网络),项目代码在容器内通过服务名即可互相访问,无需关心容器 IP。

第五步:访问

打开浏览器访问 http://localhost。完成。

选择你的技术栈:按需组合服务

上面的快速开始只运行了一套固定组合。Laradock 支持按需替换成任意服务组合,可选服务包括:

nginx、apache2、caddy、php-fpm、mysql、postgres、mariadb、mongo、redis、memcached、rabbitmq、beanstalkd、workspace 等等。

例如改用 Apache + PostgreSQL + Redis:

docker compose up -d workspace apache2 postgres redis

记住一条规律:容器名 = 目录名。想用哪个服务,就把该服务所在目录名(如 php-fpm)传给 docker compose up -d 即可。每个服务都是独立容器、独立网络隔离,互不冲突,用完 docker compose stop 随时停掉。

常用命令速查

目的 命令
列出正在运行的容器 docker-compose ps
查看某个容器的日志 docker logs {容器名称}
停止所有容器(保留数据) docker-compose stop
删除所有容器 docker-compose down

注:仓库同时提供 docker compose(v2 新语法)与 docker-compose(v1 旧命令)两种写法;由于本项目依赖 Compose v2.20+ 的 include 特性,推荐统一使用 docker compose 形式。

支持的技术栈:几乎任何 PHP 项目都能跑

Laradock 提供了应用所需的 PHP 运行时、Web 服务器、数据库和后台服务,因此可以运行几乎任何 PHP 框架、CMS 或电商平台:

  • 框架:Laravel、Symfony、CodeIgniter、Yii、Laminas(Zend Framework)、CakePHP、Phalcon、Slim、Lumen、FuelPHP
  • CMS:WordPress、Drupal、Joomla、October CMS、Statamic、Craft CMS、TYPO3、Concrete CMS、Grav
  • 电商:Magento、WooCommerce、PrestaShop、OpenCart、Sylius、Bagisto
  • 应用:Moodle、MediaWiki、phpBB、Matomo

……或是不依赖任何框架的原生 PHP。

主要特性一览

  • 预配置技术栈:70 多个开箱即用的容器(Nginx、Apache、Caddy、PHP-FPM、MySQL、PostgreSQL、MariaDB、MongoDB、Redis、Memcached、Elasticsearch、RabbitMQ、Beanstalkd 等等)。
  • 一体化开发终端:在现成的 workspace 容器内运行 Artisan、Composer、Node 以及项目所需的任何命令行工具,宿主机上无需安装任何东西。
  • 轻松切换版本:在同一个地方切换 PHP(5.6–8.5)、数据库或其他服务的版本。
  • 与项目无关:适用于 Laravel、Symfony、WordPress、Drupal、Magento 或原生 PHP。
  • 跨平台:在 Linux、macOS 和 Windows 上提供完全一致的环境。
  • 模块化:只运行你需要的容器,任意组合。
  • 新手友好:克隆仓库、复制 env 文件、运行 docker compose up 即可。

其中"轻松切换版本"的实现可以直接在 .env.example 中看到:PHP_VERSION=8.4 这一行(注释中列出了所有可取值:8.5 - 8.4 - 8.3 - 8.2 - 8.1 - 8.0 - 7.4 - 7.3 - 7.2 - 7.1 - 7.0 - 5.6)会通过构建参数传给 workspace 与 php-fpm 镜像(见 workspace/compose.yml 中的 LARADOCK_PHP_VERSION=${PHP_VERSION})。修改该值后重新构建镜像即可切换 PHP 版本,老项目也能在旧版 PHP 上"复活",且不影响宿主机自身的 PHP 环境。

Workspace 详解:你的一体化开发终端

workspace 是一个预装了 PHP、Composer、Node、Git 以及数十种开发工具的命令行环境,让你在容器内运行项目所需的一切命令,而不必在自己的机器上安装任何东西。

进入容器,在里面工作:

docker-compose exec workspace bash

artisan、composer、phpunit、npm、git 全部开箱即用,宿主机无需安装 PHP、Composer、Node,也不会有版本冲突。停止项目后,你的设备上不会留下任何痕迹。

从 workspace/compose.yml 可以看到这个容器的"家底"——它通过上百个构建参数控制内置工具:PHP 扩展(Xdebug、Swoole、Phalcon、Mongo、AMQP 等)、前端工具链(Node、Yarn、pnpm、Gulp、Vue CLI、Angular CLI)、CMS 工具(Drush、WP-CLI、Drupal Console)、运维工具(Terraform、Protoc、JDK、Docker Client)等等,均以 INSTALL_* 开关控制是否安装。

为什么这很重要:

  • 秒级启动:所有工具都已安装配置完毕,无需任何设置;克隆项目即可开始工作。
  • 保持机器纯净:一切都在容器内运行;宿主机永远不会被装上 PHP、Composer、Node 或任何 CLI 工具,结束后也不会留下任何痕迹。
  • 隔离每个项目:每个项目运行在各自的 PHP 和数据库版本上,彼此互不冲突。
  • 复活老项目:在旧版 PHP(5.6、7.x)上运行历史项目,而不影响你系统本身的 PHP 版本。

深入 .env:核心配置项解析

.env 是 Laradock 的"单点配置"。下面按类别解析 .env.example 中的核心配置项:

路径配置

# 宿主机上你的应用代码所在路径(Laradock 克隆位置的上级目录)
APP_CODE_PATH_HOST=../

# 代码挂载到容器内的路径
APP_CODE_PATH_CONTAINER=/var/www

# 可添加挂载标志,提升 macOS/Windows 下的文件同步性能
APP_CODE_CONTAINER_FLAG=:cached

# 所有存储系统的数据目录(每个数据库引擎在其中有自己的子目录,如 mysql/、postgres/)
DATA_PATH_HOST=~/.laradock/data

注意:数据库引擎不会降级——如果你修改了 *_VERSION 后数据库容器反复重启,要么把版本改回与现有数据一致,要么删除 DATA_PATH_HOST 下对应引擎的子目录重新开始(会删除该数据库的本地数据)。

Docker Compose 相关

# 选择要包含的 compose 文件
COMPOSE_FILE=docker-compose.yml

# Windows 下需将分隔符从 : 改为 ;
COMPOSE_PATH_SEPARATOR=:

# 容器名前缀;多项目共用一套 laradock 时,改这里可让每个项目拥有独立容器
COMPOSE_PROJECT_NAME=laradock

版本与运行环境

# PHP 版本(workspace 与 php-fpm 共用),可取值:8.5 - 8.4 - 8.3 - 8.2 - 8.1 - 8.0 - 7.4 - 7.3 - 7.2 - 7.1 - 7.0 - 5.6
PHP_VERSION=8.4

# Phalcon 扩展版本(5.0.0+)
PHALCON_VERSION=5.0.0

# Docker 宿主机 IP(会追加到容器的 /etc/hosts)
DOCKER_HOST_IP=10.0.75.1

# 远程解释器配置(用于 IDE 调试)
PHP_IDE_CONFIG=serverName=laradock

# Windows 用户修复应用路径问题
COMPOSE_CONVERT_WINDOWS_PATHS=1

# 需要更换软件源(例如国内网络)时改为 true
CHANGE_SOURCE=false

服务级配置示例

.env 中还可以覆盖单服务的配置(它总是赢过各服务目录的 defaults.env):

# Redis 密码
REDIS_PASSWORD=secret_redis

# PostgreSQL 版本与账号
POSTGRES_CLIENT_VERSION=15
POSTGRES_DB=default
POSTGRES_USER=default
POSTGRES_PASSWORD=secret
POSTGRES_PORT=5432

# PHP-FPM 扩展开关
PHP_FPM_INSTALL_BCMATH=true
PHP_FPM_INSTALL_MEMCACHED=false
PHP_FPM_INSTALL_PGSQL=false

# Varnish 后端端口
VARNISH_BACKEND_PORT=81

各服务完整的默认配置分布在对应目录的 defaults.env 文件中,例如 nginx/defaults.env 定义了 HTTP/HTTPS 端口(80/443)、日志路径、站点配置路径、PHP-FPM 上游容器与端口(php-fpm:9000);mysql/defaults.env 定义了可选的 MySQL 版本(5.7、8.0、8.4、9.0)、默认库名/用户名/密码及初始化脚本目录。

理解底层架构:Compose include 机制

新版 Laradock 的 docker-compose.yml 结构非常精简:顶部声明共享网络(frontend、backend)与共享数据卷,主体是一长串 include 指令——把每个服务目录下的 compose.yml 全部纳入主编排文件:

networks:
  frontend:
    driver: ${NETWORKS_DRIVER}
  backend:
    driver: ${NETWORKS_DRIVER}

include:
  - path: adminer/compose.yml
    project_directory: .
    env_file: adminer/defaults.env
  - path: nginx/compose.yml
    project_directory: .
    env_file: nginx/defaults.env
  # ... 每个服务一行

这种"根编排 + 服务子编排"的设计带来两个直接好处:

  1. 按需加载:虽然 include 会加载所有服务定义,但你只 up 需要的那些容器,未启动的服务只是"定义存在",不占用资源;
  2. 配置就近:每个服务的端口、路径、账号等默认值都放在自己的目录里(defaults.env),要覆盖只需在根 .env 加一行。

这也解释了为什么要求 Compose v2.20+——include 关键字是较新版本的 Compose 规范能力(laradock 脚本中通过 compose_version_ok 强制校验该版本)。

进阶:Laradock CLI(可选但推荐)

仓库根目录的 laradock 是一个纯 Bash 编写的可执行脚本(约 1400 行),是对 docker compose 的"透明糖衣"封装。它遵循三条设计契约:无状态、不生成多余文件、每条命令都会打印它实际执行的 docker compose 命令。直接使用 docker compose 也完全可行,两者等效。

核心命令:

命令 作用
./laradock start 启动整套服务;首次运行会进入交互式向导(自动检测框架、预填答案,回车即可一路确认),之后直接启动并打印访问地址与凭据
./laradock setup 随时重开向导,用于增删服务、切换 PHP 版本、添加 Xdebug 等工具
./laradock workspace 进入 Workspace 开发终端(内含 php、composer、node、git)
./laradock stop / restart / rebuild / logs 停止(保留数据)/ 重启 / 重建 / 查看日志
./laradock info 显示运行中的服务、URL 与凭据
./laradock doctor 诊断常见问题
./laradock <其他> 直接透传给 docker compose <其他>

从脚本源码可以看到它的一些细节:

  • 框架自动检测(detect_framework):通过识别特征文件判断项目类型——artisan 文件 → Laravel;wp-settings.php/wp-config.php → WordPress;symfony.lock/config/bundles.php → Symfony;core/lib/Drupal.php → Drupal;否则是通用 PHP;
  • 向导只写 .env(cmd_setup):所有回答最终只落为 .env 中的覆盖项(如 COMPOSE_PROJECT_NAME、DATA_PATH_HOST、PHP_VERSION、APP_CODE_PATH_HOST、LARADOCK_SERVICES),未改动的工具开关不写任何行,.env 始终保持"你做过选择的差异集";
  • 透传设计:./laradock logs -f nginx 与 docker compose logs -f nginx 完全等价,学习成本为零。

常见问题与排查思路

  1. 数据库容器反复重启:通常是改了数据库大版本、而旧数据无法被新版本读取。按 .env.example 的提示,把版本改回去,或删除 DATA_PATH_HOST 下对应引擎子目录重建数据。
  2. docker-compose 报语法错误:请确认使用 Docker Compose v2.20+(docker compose version),本项目依赖 include 语法。
  3. 国内网络拉取镜像慢:在 .env 中设置 CHANGE_SOURCE=true 更换软件源,并可按需配置 WORKSPACE_NPM_REGISTRY 等镜像参数。
  4. 宿主机没有 PHP,怎么跑 artisan:进入 Workspace 容器执行——docker compose exec workspace bash,之后 php artisan、composer、npm 全部可用。
  5. 多项目同时开发:为每个项目克隆一份 Laradock,或通过 COMPOSE_PROJECT_NAME 区分容器前缀,让各项目的容器彼此独立。

小结

Laradock 的价值在于把"环境搭建"这一 PHP 项目开发中最枯燥、最易踩坑的环节,压缩为"克隆 + 一条命令"。本文从快速开始、技术栈选择、.env 核心配置、Compose 架构到 Workspace 终端与 CLI 脚本,完整覆盖了 README-zh.md 的全部内容,并结合仓库源码补充了配置覆盖机制、include 架构、框架自动检测等底层细节。无论你是刚接触 Docker 的新手("先用 Docker"),还是想理解其编排原理的进阶用户("后学习 Docker"),都可以对照本文在自己的 PHP 项目上落地一套干净、可复现的开发环境。

登录后查看全文
laradock