Laradock 使用指南:基于 Docker 的完整 PHP 开发环境搭建与配置详解
Laradock 使用指南:基于 Docker 的完整 PHP 开发环境搭建与配置详解
本文以 Laradock 官方中文文档(README-zh.md)为核心骨架,结合仓库内
docker-compose.yml、.env.example、laradockCLI 脚本及各服务目录下的真实配置(如 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 顶部有一段重要的配置机制说明,值得先读懂:
- 将
.env.example复制为.env,它保存所有服务共享的配置(路径、PHP 版本、项目名); - 每个服务还自带一份已填好默认值的配置:
mysql/defaults.env、nginx/defaults.env等,你不需要复制或编辑这些文件; - 想改任何配置(共享或单服务的),在
.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
# ... 每个服务一行
这种"根编排 + 服务子编排"的设计带来两个直接好处:
- 按需加载:虽然
include会加载所有服务定义,但你只up需要的那些容器,未启动的服务只是"定义存在",不占用资源; - 配置就近:每个服务的端口、路径、账号等默认值都放在自己的目录里(
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完全等价,学习成本为零。
常见问题与排查思路
- 数据库容器反复重启:通常是改了数据库大版本、而旧数据无法被新版本读取。按
.env.example的提示,把版本改回去,或删除DATA_PATH_HOST下对应引擎子目录重建数据。 docker-compose报语法错误:请确认使用 Docker Compose v2.20+(docker compose version),本项目依赖include语法。- 国内网络拉取镜像慢:在
.env中设置CHANGE_SOURCE=true更换软件源,并可按需配置WORKSPACE_NPM_REGISTRY等镜像参数。 - 宿主机没有 PHP,怎么跑 artisan:进入 Workspace 容器执行——
docker compose exec workspace bash,之后php artisan、composer、npm全部可用。 - 多项目同时开发:为每个项目克隆一份 Laradock,或通过
COMPOSE_PROJECT_NAME区分容器前缀,让各项目的容器彼此独立。
小结
Laradock 的价值在于把"环境搭建"这一 PHP 项目开发中最枯燥、最易踩坑的环节,压缩为"克隆 + 一条命令"。本文从快速开始、技术栈选择、.env 核心配置、Compose 架构到 Workspace 终端与 CLI 脚本,完整覆盖了 README-zh.md 的全部内容,并结合仓库源码补充了配置覆盖机制、include 架构、框架自动检测等底层细节。无论你是刚接触 Docker 的新手("先用 Docker"),还是想理解其编排原理的进阶用户("后学习 Docker"),都可以对照本文在自己的 PHP 项目上落地一套干净、可复现的开发环境。