使用wp-env工具搭建wordPress本地开发环境

“wp-env” 是 WordPress 官方推荐的本地开发环境工具，主要用于快速搭建轻量化的 WordPress 本地开发环境，方便开发者调试主题、插件或测试 WordPress 核心功能，无需手动配置服务器、数据库等复杂环境。

本该通过执行wp-env start 命令，直接一步到位的事。但由于国内网络因素，多了些弯弯绕绕，折腾了好几天，终于搭建成功，效果如下图。趁着记忆新鲜，比较备完。

配置步骤

1：安装Docker 桌面端Docker Desktop

2：全局安装 wp-env 工具（WordPress 环境管理工具），运行命令：npm -g install @wordpress/env

3：在终端中，切换到已有的插件目录、主题目录，或新建一个工作目录并进入该目录。

4：在终端中运行 wp-env start 命令，启动本地 WordPress 环境。

5：脚本执行完成后，访问 http://localhost:8888/wp-admin，使用默认用户名 admin 和默认密码 password 登录 WordPress 后台。

执行wp-env start时碰到问题排查

问题一：相关注意点

注意1：wp-env 必须依赖 Docker Desktop 才能正常工作

注意2：Docker Desktop在windows10 也能安装

注意3：npm -g install @wordpress/env，目的是可以在任意目录下运行该工具。

问题1：安装npm -g install @wordpress/env 跟Docker Desktop 有关系吗？

npm -g install @wordpress/env 这条命令本身是安装 wp-env 工具，哪怕你没装 Docker Desktop，这条命令也能执行（会把 wp-env 安装到你的电脑上）。

但是，如果使用wn-env命令，如用wp-env start搭建本地wordpress环境。则需要Docker Desktop，因为wp-env start脚本内容包括操作一些操作docker的docker相关命令。

所以：使用 wp-env（比如运行 wp-env start）时，必须确保 Docker Desktop 已经安装并启动，否则会报错。

问题2：wp-env start 他跟 Docker Desktop 有啥关系？

wp-env start 时，这个命令会向 Docker Desktop 发送一系列指令。而 Docker Desktop 收到这些指令后，会实际完成以下工作：

1：拉取所需的软件镜像（比如 WordPress 官方镜像、MySQL 镜像）；

2：创建独立的容器（相当于一个 “迷你虚拟机”）；

3：在容器内自动配置好各组件之间的关联（比如让 WordPress 连接到数据库）；

4：启动容器，让本地环境真正跑起来。

问题3：failed to resolve reference “docker.io/library/mariadb:lts”: … 连接超时

Error response from daemon: failed to resolve reference “docker.io/library/mariadb:lts”: failed to do request: Head “https://registry-1.docker.io/v2/library/mariadb/manifests/lts”: dialing registry-1.docker.io:443 container via direct…

原因：wp-env 需要通过 Docker 拉取 mariadb（数据库）、phpmyadmin 等镜像，但由于国内网络原因，无法连接到 Docker 官方镜像仓库。

解决过程：原先直接在Docker Desktop 中配置阿里云镜像加速源。但是不行！咨询阿里云客户，得知不能用了。

为了解决这个问题，我走了哪些弯路呢？

弯路1：配置阿里云镜像加速，重新执行wp-env start。错误：mysql Error unknown: failed to resolve reference … 403 Forbidden，提示使用的阿里云镜像加速地址无效。

弯路2：既然要在阿里云服务器上才能用镜像加速，我可否在服务器上执行wp-env start 然后移到本地window上的Docker Desktop？折腾了一段，我用境外阿里云服务器配置成功了，但是要把相关docker镜像下载本地时，下载速度慢的可怜，只有100k左右，我看了下镜像大小，有好几G，这要下载啥时候啊。直接放弃。

弯路3：通过阿里云洛杉矶 ECS 云服务器搭建代理，解决本地 Docker 拉取镜像的网络问题（尤其是国际镜像仓库访问受限的情况），用 tinyproxy 搭建轻量代理，折腾了一段，代理生效了，但是一直卡在：Connection was reset 表示 “连接被远程端重置”。恶心死了，最后放弃。

最后，还是在知乎上，找到docker加速地址，感谢热心网友分享。

https://www.zhihu.com/question/1925592578650272377/answer/1938684697963103618

问题4：fatal: unable to access ‘https://github.com/WordPress/wordpress-develop.git/’: Recv failure: Connection was reset

wp-env 在搭建测试环境（PHPUnit 相关）时，默认会尝试从 GitHub 克隆 wordpress-develop.git 仓库，而你的网络环境导致克隆失败。

这次是碰到github网络不稳定问题。

解决办法：

先手工下载

https://github.com/WordPress/wordpress-develop.git

和

https://github.com/WordPress/WordPress.git

，上传到gitee中我的账号。

https://gitee.com/chenzz91/WordPress.git

和

https://gitee.com/chenzz91/wordpress-develop.git

通过 Git 的 url.insteadOf 配置，让 wp-env 自动将 GitHub 地址替换为你的 Gitee 仓库地址。

打开终端（Git Bash 或命令提示符），执行以下命令，将两个 GitHub 仓库地址分别替换为你的 Gitee 地址：

# 替换 WordPress 核心仓库（https://github.com/WordPress/WordPress.git → 你的 Gitee 地址）
git config --global url."https://gitee.com/chenzz91/WordPress.git".insteadOf "https://github.com/WordPress/WordPress.git"

# 替换 wordpress-develop 测试仓库（https://github.com/WordPress/wordpress-develop.git → 你的 Gitee 地址）
git config --global url."https://gitee.com/chenzz91/wordpress-develop.git".insteadOf "https://github.com/WordPress/wordpress-develop.git"

执行以下命令，确认替换规则已正确添加：

git config --global --get-regexp insteadOf

再重新执行wp-env start

注意 1：WordPress.git，一定要加上版本标签。不然会拉取失败：

task: { commands: [ ‘fetch’, ‘–tags’, ‘origin’, ‘6.8.2’ ], format: ‘utf-8’, parser: [Function: parseFetchResult] }

注意2：wordpress-develop.git，主开发分支名为 trunk，而非常见的 main 或 master。不然也会拉取失败：

task: { commands: [ ‘fetch’, ‘origin’, ‘trunk’, ‘–depth’, ‘1’ ], format: ‘utf-8’, parser: [Function: parser] }

问题5：提示 “Package ‘git’ has no installation candidate”

#21 ERROR: process “/bin/sh -c apt-get -qy install git” did not complete successfully: exit code: 100

Docker 镜像中使用的 Debian 系统版本（如 stretch/buster）已停止官方支持，导致 apt-get 无法从默认源找到 git 安装包。日志中虽尝试修改源为归档地址（archive.debian.org），但配置不完整导致失败。

[tests-wordpress 5/23] RUN sed -i ‘/stretch-updates/d’ /etc/apt/sources.list

sed -i 's|deb.debian.org/debian stretch|archive.debian.org/debian stretch|g'

上面错误日志说明 Docker 镜像用的是 Debian 9 Stretch—— 这个版本早在 2022 年就已停止所有支持，进入 “归档状态”。

wp-env 自动用 wordpress:latest → 这个 latest 镜像底层是过时的 Debian 9 → Debian 9 的软件源失效 → 装不上 git → 报错。

解决：

.wp-env.json文件配置，指定php最新版本：

{
	"phpVersion": "8.3",
	"plugins": [ "." ]
}

wp-env 允许通过 phpVersion 配置指定 PHP 版本，间接使用对应的 Docker 镜像（避免旧系统问题）

问题6：cli 和 tests-cli 服务构建失败

#40 [cli  5/14] RUN apk --no-cache add autoconf                 dpkg-dev dpkg           file            g++            gcc              libc-dev                make            pkgconf                 re2c && touch /usr/local/etc/php/php.ini
#40 0.346 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
#40 109.2 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
#40 1386.2 WARNING: fetching https://dl-cdn.alpinelinux.org/alpine/v3.22/community: IO ERROR
#40 1386.2 (1/22) Installing m4 (1.4.19-r4)
#40 1386.2 ERROR: m4-1.4.19-r4: DNS lookup error

..........

#40 ERROR: process "/bin/sh -c apk --no-cache add $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini" did not complete successfully: exit code: 22
------
 > [tests-cli  5/14] RUN apk --no-cache add autoconf            dpkg-dev dpkg           file            g++            gcc              libc-dev                make            pkgconf                 re2c && touch /usr/local/etc/php/php.ini:
1386.2 (19/22) Installing g++ (14.2.0-r6)
1386.2 ERROR: musl-dev-1.2.5-r10: DNS lookup error
1386.2 ERROR: g++-14.2.0-r6: DNS lookup error
1386.2 (20/22) Installing make (4.4.1-r3)
1386.2 ERROR: make-4.4.1-r3: DNS lookup error
1386.2 (21/22) Installing mariadb-client-perl (11.4.8-r0)
1386.2 ERROR: mariadb-client-perl-11.4.8-r0: DNS lookup error
1386.2 (22/22) Installing re2c (4.2-r0)
1386.2 ERROR: re2c-4.2-r0: DNS lookup error
1386.2 22 errors; 94 MiB in 75 packages

分析日志：tests-cli服务在执行apk –no-cache add时出现大量 “DNS lookup error”，最终 exit code 22 失败。先定位问题核心：错误集中在cli和tests-cli服务，提示 DNS 解析失败，无法获取 Alpine Linux 的软件包（如m4、perl等）。而wordpress和tests-wordpress服务基于 Debian，虽然之前替换了源，但cli服务用的是 Alpine 系统，默认源是dl-cdn.alpinelinux.org，国内访问可能受限，导致 DNS 解析失败或连接超时。

#32 [cli  4/14] RUN apk update
#32 145.1 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
#32 697.6 v3.22.1-491-g944002f0618 [https://dl-cdn.alpinelinux.org/alpine/v3.22/main]
#32 697.6 v3.22.1-494-g8bea4f0b66f [https://dl-cdn.alpinelinux.org/alpine/v3.22/community]
#32 697.6 OK: 26325 distinct packages available
#32 DONE 697.7s

cli服务步骤 32 执行apk update时，获取 Alpine 的 APKINDEX.tar.gz 耗时极长（697.7s），后续步骤 40 安装依赖时直接出现 DNS 错误，说明 Alpine 的默认源在当前网络环境下不可用。之前的配置只覆盖了 Debian 的源，没处理 Alpine 的cli服务，这是遗漏点。

解决方案：补充 Alpine 源替换配置

docker-compose.override.yml 中新增对 cli 和 tests-cli 服务的配置，将其 Alpine 源替换为阿里云镜像（国内加速）.

version: '3.8'

services:
  # 覆盖 WordPress 服务的构建过程，替换软件源
  wordpress:
    build:
      args:
        # 替换 Debian 源为阿里云镜像（适用于 Debian 12/trixie）
        DEBIAN_MIRROR: "http://mirrors.aliyun.com/debian/"
        DEBIAN_SECURITY_MIRROR: "http://mirrors.aliyun.com/debian-security/"

  # 若启用测试环境，同步覆盖 tests-wordpress 服务
  tests-wordpress:
    build:
      args:
        DEBIAN_MIRROR: "http://mirrors.aliyun.com/debian/"
        DEBIAN_SECURITY_MIRROR: "http://mirrors.aliyun.com/debian-security/"

  cli:
    build:
      args:
        ALPINE_MIRROR: "https://mirrors.aliyun.com/alpine/"

  tests-cli:
    build:
      args:
        ALPINE_MIRROR: "https://mirrors.aliyun.com/alpine/"

后续注意

执行wp-env start 后，正常结果如下：

在 Windows 系统中，wp-env 基于 Docker 运行，无需手动 “保存” 环境状态——Docker 会自动保留容器和数据的持久化状态。你只需按正常流程停止环境、关机即可，明天重启后能直接恢复。

执行停止命令

wp-env stop

恢复 wp-env 环境

首先确保 Docker Desktop 已启动（Windows 桌面找 Docker 图标，双击打开，等待状态栏显示 “Running”）。

打开终端，进入项目目录

wp-env start