Docker Compose 搭建本地 WordPress 开发环境：从配置到运行

为什么本地 WordPress 开发环境比在线测试更安全

WordPress 主题或插件开发时，直接在正式站点上测试风险很高——一次错误的代码提交可能导致整站崩溃、数据丢失或安全风险。本地开发环境让你可以随意修改、回滚、调试，而不会影响线上用户。

过去搭建本地 WordPress 需要手动安装 Apache 或 Nginx、PHP、MySQL，版本兼容性经常出问题，不同同事的机器环境还各不相同。现在用 Docker Compose 可以把整个技术栈打包成几个配置文件，一条命令启动，一条命令销毁，环境完全可复现。

本文面向有一定命令行基础但不熟悉 Docker 的 WordPress 开发者，从创建项目目录到成功访问本地站点，给出可逐行复制的完整流程，不涉及任何 AI 工具或生成式产品。

适合人群与前置条件

适合以下三类读者：WordPress 主题或插件开发者、需要为客户演示站点效果的设计师、以及想在本地复现线上环境进行故障排查的运维人员。

前置条件只有一项：系统上已安装 Docker Desktop。Windows 用户需要 Windows 10 专业版 21H2 或更高版本并启用 WSL 2；macOS 用户需要 macOS 12 或更高版本；Linux 用户需要 4.19 或更高内核。如果你的系统不满足这些要求，建议先升级操作系统或联系 IT 部门协助。

关键判断：Docker Compose 不是 Docker 的替代品，而是 Docker 的编排工具。它通过一个 YAML 文件描述多容器应用，让启动、停止、重建变得可重复。你不需要理解 Kubernetes 或 Swarm 才能使用它。

步骤1：下载并安装 Docker Desktop

访问 Docker 官网下载对应系统的 Docker Desktop 安装包。Windows 用户下载 Docker Desktop for Windows，macOS 用户根据芯片类型选择 Apple Silicon 或 Intel 版本，Linux 用户按发行版选择对应安装包。

安装过程中 Windows 用户需要启用 WSL 2 和虚拟机平台功能，macOS 用户只需按向导完成安装。安装完成后启动 Docker Desktop，等待右下角状态图标变为绿色，表示 Docker Engine 已就绪。

验证安装是否成功，在终端执行以下命令：

docker version

输出应同时显示 Client 和 Server 版本信息。如果只显示 Client 而没有 Server，说明 Docker Engine 未正常启动，请重启 Docker Desktop 后重试。

步骤2：创建项目目录结构

在本地选择一个工作目录，例如 ~/wordpress-dev，在其中创建以下文件结构：

wordpress-dev/
├── docker-compose.yml
├── wp-content/
│   ├── themes/
│   ├── plugins/
│   └── uploads/
└── .env

wp-content 目录用于挂载 WordPress 的主题、插件和上传文件，这样容器销毁后你的开发成果不会丢失。.env 文件用于存放数据库密码等敏感配置，不会被提交到版本控制。

步骤3：编写 docker-compose.yml

在项目根目录创建 docker-compose.yml，内容如下：

services:
  db:
    image: mysql:8.0
    container_name: wp-dev-db
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    ports:
      - "3306:3306"

  wordpress:
    image: wordpress:latest
    container_name: wp-dev-wordpress
    restart: always
    depends_on:
      - db
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - ./wp-content/themes:/var/www/html/wp-content/themes
      - ./wp-content/plugins:/var/www/html/wp-content/plugins
      - ./wp-content/uploads:/var/www/html/wp-content/uploads
    ports:
      - "8080:80"

volumes:
  db_data:

这个配置定义了两个服务：MySQL 8.0 数据库和 WordPress 官方镜像（latest 标签）。WordPress 容器通过 depends_on 等待数据库就绪后启动，三个 wp-content 子目录通过卷挂载到本地，数据库数据存储在命名卷 db_data 中。

关于版本选择，wordpress:latest 始终指向 WordPress 官方发布的最新稳定版。如果你需要固定版本以保证环境一致性，可以将标签替换为具体版本号，例如 wordpress:6.7，具体可用标签以 Docker Hub 官方仓库为准。

步骤4：配置环境变量

创建 .env 文件，填入以下内容：

DB_ROOT_PASSWORD=your_secure_root_password
DB_PASSWORD=your_secure_db_password

将密码替换为你自己设定的强密码。.env 文件会被 Docker Compose 自动读取，docker-compose.yml 中的 ${DB_ROOT_PASSWORD} 和 ${DB_PASSWORD} 会被替换为实际值。确保 .env 已加入 .gitignore，避免密码泄露。

步骤5：启动服务

在项目根目录打开终端，执行：

docker compose up -d

-d 参数表示后台运行。首次执行时 Docker 会拉取 mysql:8.0 和 wordpress:latest 两个镜像，根据网络速度可能需要几分钟。如果拉取失败，检查网络连接或尝试更换 Docker 镜像源。

启动完成后执行以下命令确认两个容器都在运行：

docker compose ps

输出应显示 db 和 wordpress 两个服务状态均为 Up。如果某个服务显示 Exited，执行 docker compose logs <service_name> 查看具体错误信息。

步骤6：访问并初始化 WordPress

打开浏览器访问 http://localhost:8080，你会看到 WordPress 安装向导。选择语言、设置站点标题、管理员用户名和密码，完成初始化。

初始化完成后即可登录后台，开始主题或插件开发。本地环境完全独立于线上站点，你可以放心地进行任何测试，包括删除数据、修改核心文件、安装测试插件等。

结果验证

验证本地环境是否配置正确，依次检查以下几点：

• 访问 http://localhost:8080/wp-admin 可以进入后台管理界面
• 在本地 wp-content/themes 目录下新建主题文件，刷新前台即可看到效果，无需进入容器
• 在本地 wp-content/plugins 目录放入插件文件夹，后台即可识别并启用
• 执行 docker compose logs wordpress 查看 WordPress 日志，确认无 Error establishing a database connection 等错误

如果以上全部正常，说明本地开发环境搭建成功，可以开始日常开发工作。

常见问题与排错

端口冲突：如果 8080 端口已被占用，修改 docker-compose.yml 中 WordPress 的 ports 配置，例如改为 "8081:80"，然后执行 docker compose up -d 重启。你也可以用 lsof -i :8080 查看占用端口的进程。

数据库连接失败：WordPress 日志中如果出现 Error establishing a database connection，检查 .env 文件中的密码是否与 docker-compose.yml 中一致，确认 db 容器状态为 Up。注意 WORDPRESS_DB_HOST 必须写 db:3306 而不是 localhost:3306，因为在 Docker 网络中服务名就是主机名。

中文乱码：MySQL 8.0 默认使用 utf8mb4 字符集，通常不会出现乱码。如果主题或插件出现编码问题，检查 PHP 文件的编码格式是否为 UTF-8 without BOM。

容器无法启动：执行 docker compose logs <service_name> 查看具体错误信息。常见原因是镜像拉取失败（网络问题）或端口冲突。如果镜像拉取超时，可以尝试单独执行 docker pull mysql:8.0 和 docker pull wordpress:latest 手动拉取。

清理与重置

开发过程中需要重置环境时，执行：

docker compose down -v

-v 参数会同时删除数据卷，数据库和 WordPress 文件将恢复到初始状态。注意这会删除所有数据库数据，执行前请确认已备份。

如果只想停止服务但保留数据，执行 docker compose down 即可。下次执行 docker compose up -d 时，容器会基于已有数据重新启动。

下一步建议

本地环境搭建完成后，建议配合 Git 进行版本控制，将 wp-content/themes 和 wp-content/plugins 目录纳入仓库管理，docker-compose.yml 和 .env 的模板版本也一并提交。

对于需要多环境切换的项目，可以创建多个 .env 文件（如 .env.local、.env.staging）配合 docker compose --env-file .env.staging up -d 参数使用，实现不同数据库配置的快速切换。

如果你需要在本地模拟 CDN、对象存储或邮件服务，可以进一步在 docker-compose.yml 中添加 MinIO、MailHog 等开源服务，构建更完整的本地测试环境。这些扩展同样遵循 Docker Compose 的配置模式，不需要额外学习新的编排工具。