144 lines
7.0 KiB
Markdown
144 lines
7.0 KiB
Markdown
# 开始使用 wp-env
|
||
|
||
[@wordpress/env](https://www.npmjs.com/package/@wordpress/env) 包（简称 `wp-env`）可帮助您快速搭建本地 WordPress 环境（站点），用于插件和主题的开发测试，无需任何额外配置。
|
||
|
||
在按照本指南操作前，请先确保已安装 [Node.js 开发工具](/docs/getting-started/devenv#node-js-development-tools)。
|
||
|
||
|
||
|
||
## 快速开始
|
||
|
||
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） |