@wordpress/env 包（wp-env）可让您无需任何额外配置即可为构建和测试插件和主题设置本地 WordPress 环境（站点）。

在遵循本指南之前，如果尚未安装 Node.js 开发工具，请先进行安装。

wp-env 基础架构图

快速入门

  1. 按照您操作系统的说明下载、安装并启动 Docker Desktop。
  2. 在终端中运行 npm -g install @wordpress/env 以全局安装 wp-env。
  3. 在终端中导航到现有的插件目录、主题目录或新的工作目录。
  4. 在终端中运行 wp-env start 以启动本地 WordPress 环境。
  5. 脚本运行后，导航至 http://localhost:8888/wp-admin，并使用用户名 admin 和密码 password 登录 WordPress 仪表板。

设置 Docker Desktop

wp-env 工具使用 Docker 创建运行本地 WordPress 站点的虚拟机。Docker Desktop 应用程序对小型企业、个人用途、教育和非商业开源项目免费。有关更多信息，请参阅其 常见问题解答。

使用下方的链接下载并安装适用于您操作系统的 Docker Desktop。

如果您使用的是 20.04.1 之前的 Ubuntu 版本，请参见下方的额外 故障排除说明。

安装成功后，启动 Docker Desktop 应用程序并按照提示进行设置。通常应使用推荐的（默认）设置，创建 Docker 账户是可选的。

安装和运行 wp-env

wp-env 工具用于使用 Docker 创建本地 WordPress 环境。因此，在设置好 Docker Desktop 后，打开终端并运行以下命令安装 wp-env：

npm -g install @wordpress/env

这将全局安装 wp-env，允许从任何目录运行该工具。要确认已安装且可用，请运行 wp-env --version，版本号应该会显示。

接下来，在终端中导航到现有的插件目录、主题目录或新的工作目录并运行：

wp-env start

脚本完成后，您可以访问本地环境：http://localhost:8888。使用用户名 admin 和密码 password 登录 WordPress 仪表板。

某些项目（如 Gutenberg）包含其特定的 wp-env 配置，文档可能会提示您运行 npm run wp-env start 而不是其他命令。

有关控制 Docker 环境的更多信息，请参阅 @wordpress/env 包 的说明文件。

在哪里运行 wp-env

wp-env 工具几乎可以在任何地方运行。在使用脚本开发单个插件时，从包含该插件的目录运行 wp-env start 可以自动挂载并激活该插件。从正在开发主题的目录运行时，此方法也适用于主题。

如果您从不是插件或主题的目录运行 wp-env start，将创建通用的 WordPress 环境。脚本将显示以下警告，但如果这是您的意图，请忽略它。

!! Warning: could not find a .wp-env.json configuration file and could not determine if 'DIR' is a WordPress installation, a plugin, or a theme.

您还可以使用 .wp-env.json 配置文件创建可与多个插件和/或主题配合使用的环境。有关更多配置详情，请参阅 @wordpress/env 包 的说明文件。

卸载或重置 wp-env

如果您需要重新开始或想删除已安装的内容，以下是几条说明。

  • 如果只想重置并清理 WordPress 数据库，请运行 wp-env clean all
  • 若要完全移除特定项目的本地环境，请运行 wp-env destroy
  • 若要全局卸载 wp-env 工具，请运行 npm -g uninstall @wordpress/env

故障排除

常见错误

使用 wp-env 时，通常会遇到错误：Error while running docker-compose command

  • 检查 Docker Desktop 是否已启动并运行。
  • 检查 Docker Desktop 仪表板中的日志，重启或移除现有虚拟机。
  • 然后尝试重新运行 wp-env start。

如果您看到错误：Host is already in use by another container

  • 您尝试启动的容器已经在运行，或者另一个容器正在运行。您可以通过从启动它的目录运行 wp-env stop 来停止现有容器。
  • 如果您不记得启动 wp-env 的目录，可以通过运行 docker stop $(docker ps -q) 来停止所有容器。这将停止所有 Docker 容器，请谨慎使用。
  • 然后尝试重新运行 wp-env start。

Ubuntu Docker 设置

如果您使用的是 20.04.1 之前的 Ubuntu 版本，在使用 wp-env 设置本地 WordPress 环境时可能会遇到错误。

要解决此问题，请首先按照 Docker 的 安装指南 操作。还需要 docker-compose，您可能需要单独安装它。请参阅 Docker compose 文档。

一旦安装了 Docker 和 wp-env，并且假设 wp-env 已全局配置，请在目录中尝试运行 wp-env start。如果您遇到此错误：

ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?

If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable.

首先，确保 Docker 正在运行。您可以通过运行 ps -ef | grep docker 进行检查，应返回类似以下内容：

/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

如果 Docker 未运行，请尝试通过运行 sudo systemctl start docker.service 启动服务。

如果 Docker 正在运行，则它未监听 WordPress 环境试图通信的方式。尝试添加以下服务覆盖文件以包含监听 tcp。请参阅 此 Docker 文档 了解如何配置 Docker daemons 的远程访问。

# /etc/systemd/system/docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376

从命令行重启服务：

sudo systemctl daemon-reload
sudo systemctl restart docker.service

重启服务后，设置环境变量 DOCKER_HOST 并尝试使用以下命令启动 wp-env：

export DOCKER_HOST=tcp://127.0.0.1:2376
wp-env start

您的环境现在应在 http://localhost:8888 设置好。

其他资源