# 开始使用 wp-env

[@wordpress/env](https://www.npmjs.com/package/@wordpress/env) 包（简称 `wp-env`）可帮助您快速搭建本地 WordPress 环境（站点），用于插件和主题的开发测试，无需任何额外配置。

在按照本指南操作前，请先确保已安装 [Node.js 开发工具](/docs/getting-started/devenv#node-js-development-tools)。

![wp-env 基础架构图](https://developer.wordpress.org/files/2023/10/wp-env-diagram.png)

## 快速开始
 
1. 根据操作系统说明下载、安装并启动 [Docker Desktop](https://www.docker.com/products/docker-desktop)
2. 在终端中运行 `npm -g install @wordpress/env` 全局安装 `wp-env`
3. 在终端中进入现有插件目录、主题目录或新建工作目录
4. 运行 `wp-env start` 启动本地 WordPress 环境
5. 脚本运行完成后，访问 <code>http://localhost:8888/wp-admin</code>，使用用户名 `admin` 和密码 `password` 登录 WordPress 管理后台

## 配置 Docker Desktop

`wp-env` 工具使用 [Docker](https://www.docker.com/) 创建运行本地 WordPress 站点的虚拟机。Docker Desktop 应用程序对小型企业、个人用户、教育机构和非商业开源项目免费。详见官方 [FAQ](https://docs.docker.com/desktop/faqs/general/#do-i-need-to-pay-to-use-docker-desktop)。

点击对应链接下载并安装适用于您操作系统的 Docker Desktop：

- [Mac 版 Docker Desktop](https://docs.docker.com/desktop/install/mac-install/)
- [Windows 版 Docker Desktop](https://docs.docker.com/desktop/install/windows-install/)
- [Linux 版 Docker Desktop](https://docs.docker.com/desktop/install/linux-install/)

若使用早于 20.04.1 的 Ubuntu 版本，请参阅下方的[故障排除说明](#ubuntu-docker-setup)。

成功安装后启动 Docker Desktop 应用程序，按提示完成设置。通常使用推荐（默认）设置即可，创建 Docker 账户为可选步骤。

## 安装并运行 `wp-env`

`wp-env` 工具用于通过 Docker 创建本地 WordPress 环境。配置好 Docker Desktop 后，在终端中运行以下命令安装 `wp-env`：

```sh
npm -g install @wordpress/env
```

此命令将全局安装 `wp-env`，使该工具可在任意目录运行。可通过运行 `wp-env --version` 验证安装，成功会显示版本号。

接着在终端中进入现有插件目录、主题目录或新建工作目录，运行：

```sh
wp-env start
```

脚本执行完毕后，即可通过 <code>http://localhost:8888</code> 访问本地环境。使用用户名 `admin` 和密码 `password` 登录 WordPress 管理后台。

<div class="callout callout-tip">
    部分项目（如 Gutenberg）包含特定的 <code>wp-env</code> 配置，文档可能会要求您运行 <code>npm run wp-env start</code> 命令
</div>

有关控制 Docker 环境的更多信息，请参阅 [@wordpress/env 包](/packages/env/README.md) 说明文档。

### 运行环境配置

`wp-env` 工具几乎可在任意目录运行。在开发单个插件时，在插件所在目录执行 `wp-env start` 可自动挂载并激活该插件。此规则同样适用于主题开发目录。

若在非插件/主题目录运行 `wp-env start`，将创建通用 WordPress 环境。此时脚本会显示以下警告，若属预期行为可忽略：

```
!! 警告：未找到 .wp-env.json 配置文件，且无法判定“DIR”是否为 WordPress 安装目录、插件或主题
```

您还可以通过 `.wp-env.json` 配置文件创建支持多插件和/或主题的环境。详细配置说明请参阅 [@wordpress/env 包](/packages/env/README.md#wp-envjson) 文档。

### 卸载或重置 `wp-env`

以下是一些操作指南，适用于需要重新开始或希望移除已安装内容的情况。

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

## 故障排除

### 常见错误

使用 `wp-env` 时，常见错误提示：`执行 docker-compose 命令时出错`

-   请检查 Docker Desktop 是否已启动并正在运行。
-   查看 Docker Desktop 控制面板中的日志，重启或移除现有的虚拟机。
-   然后尝试重新运行 `wp-env start`。

如果出现错误：`主机已被其他容器占用`

-   您尝试启动的容器已在运行，或者存在其他容器占用。您可以通过在启动该容器的目录中运行 `wp-env stop` 来停止现有容器。
-   如果不记得启动 `wp-env` 的目录，可以通过运行 `docker stop $(docker ps -q)` 停止所有容器。此操作会停止所有 Docker 容器，请谨慎使用。
-   然后尝试重新运行 `wp-env start`。

### Ubuntu Docker 设置

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

要解决此问题，请先按照 Docker 的[安装指南](https://docs.docker.com/install/linux/docker-ce/ubuntu/)进行操作。同时需要安装 `docker-compose`，您可能需要单独安装。请参阅 [Docker compose 文档](https://docs.docker.com/compose/install/)。

安装 Docker 和 `wp-env` 后，假设 `wp-env` 已全局配置，尝试在某个目录中运行 `wp-env start`。如果遇到以下错误：

```
错误：无法在 http+docker://localhost 连接到 Docker 守护进程——它是否正在运行？

如果它位于非标准位置，请使用 DOCKER_HOST 环境变量指定 URL。
```

首先，请确保 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 文档](https://docs.docker.com/config/daemon/remote-access/)。

```
# /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
```

现在您的环境应设置在 <code>http://localhost:8888</code>。

## 其他资源

- [@wordpress/env](https://www.npmjs.com/package/@wordpress/env)（官方文档）
- [Docker Desktop](https://docs.docker.com/desktop)（官方文档）
- [使用 wp-env 快速轻松地进行本地 WordPress 开发](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/)（WordPress 开发者博客）
- [wp-env：简单的 WordPress 本地环境](https://make.wordpress.org/core/2020/03/03/wp-env-simple-local-environments-for-wordpress/)（Make WordPress Core 博客）
- [`wp-env` 基础示意图](https://excalidraw.com/#json=8Tp55B-R6Z6-pNGtmenU6,_DeBR1IBxuHNIKPTVEaseA)（Excalidraw）