wp-env

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@wordpress/env (wp-env)

Zero-config, Docker-based local WordPress development environment for plugins, themes, and core.

零配置、基于Docker的本地WordPress开发环境，适用于插件、主题及核心开发。

When to use

适用场景

User asks to set up a local WordPress development environment
Project contains a
```
.wp-env.json
```
file
User mentions
```
wp-env
```
,
```
@wordpress/env
```
, or Docker-based WordPress development
User wants to run WP-CLI commands, PHPUnit tests, or debug with Xdebug locally
Triage detects a plugin or theme project that needs a local WordPress instance

wp-env or wp-playground? For a quick local WordPress, prefer the wp-playground skill by default — it's faster, disposable, and needs no Docker. Use wp-env when the task actually requires it:

the repo already contains a
```
.wp-env.json
```
a real MySQL database is needed (PHPUnit against the DB,
```
wp db
```
commands, data that survives restarts)
arbitrary commands must run inside the environment (shell access, Composer, full WP-CLI via
```
wp-env run
```
)
this is a WordPress core or Gutenberg checkout
the user explicitly asks for wp-env or Docker

wp-env can also run without Docker by using Playground as its runtime (

npx @wordpress/env start --runtime=playground

, experimental). That is still wp-env, driven by the same

.wp-env.json

, so treat it as a Docker-free fallback for a project that already carries wp-env config, not as a third option. It swaps MySQL for SQLite and drops

wp-env run

and the separate tests environment, which are most of the reasons to pick wp-env in the first place. For a quick Docker-free WordPress with no wp-env config, use the wp-playground skill directly.

用户要求搭建本地WordPress开发环境
项目包含
```
.wp-env.json
```
文件
用户提及
```
wp-env
```
、
```
@wordpress/env
```
或基于Docker的WordPress开发
用户想要在本地运行WP-CLI命令、PHPUnit测试或使用Xdebug调试
分诊流程识别到需要本地WordPress实例的插件或主题项目

选wp-env还是wp-playground？ 对于快速搭建本地WordPress，默认优先推荐使用 wp-playground 技能——它速度更快、用完即弃，且无需Docker。仅当任务确实需要时才使用 wp-env：

代码仓库已包含
```
.wp-env.json
```
需要真实的MySQL数据库（针对数据库的PHPUnit、
```
wp db
```
命令、重启后仍保留的数据）
需要在环境内运行任意命令（shell访问、Composer、通过
```
wp-env run
```
使用完整WP-CLI）
这是WordPress核心或Gutenberg的检出代码
用户明确要求使用wp-env或Docker

wp-env 也可以不使用Docker运行，将Playground作为其运行时（

npx @wordpress/env start --runtime=playground

，实验性功能）。这仍然属于wp-env，由相同的

.wp-env.json

驱动，因此应将其视为已携带wp-env配置的项目的无Docker备选方案，而非第三种选项。它将MySQL替换为SQLite，并去掉了

wp-env run

和独立的测试环境——而这两点原本是选择wp-env的主要原因。如果需要无需Docker、且没有wp-env配置的快速WordPress环境，请直接使用 wp-playground 技能。

Inputs required

所需输入信息

Docker status -- verify Docker is installed and running:
```
docker info
```
Node.js version -- must be >= 18.12.0:
```
node -v
```
Project type -- plugin, theme, or full site (check for
```
.wp-env.json
```
, plugin headers, or
```
style.css
```
theme headers)
Existing config -- read
```
.wp-env.json
```
and
```
.wp-env.override.json
```
if present

Docker状态 -- 验证Docker已安装并运行：
```
docker info
```
Node.js版本 -- 必须 >= 18.12.0：
```
node -v
```
项目类型 -- 插件、主题或完整站点（检查是否有
```
.wp-env.json
```
、插件头信息或
```
style.css
```
主题头信息）
现有配置 -- 读取
```
.wp-env.json
```
和
```
.wp-env.override.json
```
（如果存在）

Procedure

操作步骤

1. Install wp-env

1. 安装wp-env

undefined

undefined

Global (recommended)

npm -g install @wordpress/env

Or project-local

npm i @wordpress/env --save-dev

Then use: npx wp-env start

undefined

undefined

2. Start the environment

2. 启动环境

wp-env start

Default credentials:

URL: http://localhost:8888/wp-admin/
Username:
```
admin
```
Password:
```
password
```

Common start options:

```
wp-env start --update
```
-- pull latest sources and reconfigure
```
wp-env start --xdebug
```
-- enable Xdebug (debug mode)
```
wp-env start --xdebug=profile,trace
```
-- multiple Xdebug modes
```
wp-env start --auto-port
```
-- find available ports when defaults are busy

wp-env start

默认凭据：

URL: http://localhost:8888/wp-admin/
用户名:
```
admin
```
密码:
```
password
```

常用启动选项：

```
wp-env start --update
```
-- 拉取最新源码并重新配置
```
wp-env start --xdebug
```
-- 启用Xdebug（调试模式）
```
wp-env start --xdebug=profile,trace
```
-- 启用多种Xdebug模式
```
wp-env start --auto-port
```
-- 当默认端口被占用时自动寻找可用端口

3. Auto-detection (no config file)

3. 自动检测（无配置文件时）

When no

.wp-env.json

exists, wp-env scans the current directory:

Detected type	How detected	Auto-config
Plugin	`Plugin Name:` header in a root `.php` file	`{ "plugins": ["."] }`
Theme	`Theme Name:` header in `style.css`	`{ "themes": ["."] }`
Core	`wp-includes/version.php` exists	`{ "core": "." }`

当不存在

.wp-env.json

时，wp-env会扫描当前目录：

检测到的类型	检测方式	自动配置
插件	根目录 `.php` 文件中的 `Plugin Name:` 头信息	`{ "plugins": ["."] }`
主题	`style.css` 中的 `Theme Name:` 头信息	`{ "themes": ["."] }`
核心	存在 `wp-includes/version.php`	`{ "core": "." }`

4. Configure with

.wp-env.json

4. 使用

.wp-env.json

配置

Place at the project root. All fields are optional.

json

{
  "core": null,
  "phpVersion": "8.1",
  "plugins": [
    ".",
    "https://downloads.wordpress.org/plugin/akismet.zip",
    "WordPress/classic-editor"
  ],
  "themes": [],
  "port": 8888,
  "multisite": false,
  "phpmyadmin": false,
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  },
  "mappings": {
    "wp-content/mu-plugins": "./mu-plugins"
  },
  "lifecycleScripts": {
    "afterStart": "wp-env run cli wp rewrite structure /%postname%/"
  }
}

放置在项目根目录。所有字段均为可选。

json

{
  "core": null,
  "phpVersion": "8.1",
  "plugins": [
    ".",
    "https://downloads.wordpress.org/plugin/akismet.zip",
    "WordPress/classic-editor"
  ],
  "themes": [],
  "port": 8888,
  "multisite": false,
  "phpmyadmin": false,
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  },
  "mappings": {
    "wp-content/mu-plugins": "./mu-plugins"
  },
  "lifecycleScripts": {
    "afterStart": "wp-env run cli wp rewrite structure /%postname%/"
  }
}

Source string formats (for

core

plugins

themes

mappings

)

源字符串格式（用于

core

、

plugins

、

themes

、

mappings

）

Format	Example
Local path	`"."` , `"./path"` , `"../path"`
GitHub shorthand	`"WordPress/classic-editor"` , `"owner/repo#branch"`
ZIP URL	`"https://downloads.wordpress.org/plugin/akismet.zip"`
Git SSH	`"ssh://user@host/repo.git#ref"`

GOTCHA: WordPress.org plugin/theme slugs (bare names like

"akismet"

) do NOT work. Use the full ZIP URL.

格式	示例
本地路径	`"."` , `"./path"` , `"../path"`
GitHub简写	`"WordPress/classic-editor"` , `"owner/repo#branch"`
ZIP URL	`"https://downloads.wordpress.org/plugin/akismet.zip"`
Git SSH	`"ssh://user@host/repo.git#ref"`

踩坑提醒： WordPress.org插件/主题的别名（如

"akismet"

这类裸名称）不生效，请使用完整的ZIP URL。

Local overrides with

.wp-env.override.json

使用

.wp-env.override.json

进行本地覆盖

Create

.wp-env.override.json

next to

.wp-env.json

for personal settings (gitignored). Only

config

and

mappings

are merged -- all other fields (including

plugins

and

themes

arrays) fully replace the base.

在

.wp-env.json

同级目录创建

.wp-env.override.json

用于个人设置（应加入gitignore）。仅

config

和

mappings

字段会合并——所有其他字段（包括

plugins

和

themes

数组）会完全替换基础配置。

5. Run commands in containers

5. 在容器中运行命令

undefined

undefined

WP-CLI commands

wp-env run cli wp user list wp-env run cli wp plugin list wp-env run cli wp option update blogname "My Site" wp-env run cli "wp rewrite structure /%postname%/"

Run commands in a specific directory

wp-env run cli --env-cwd=wp-content/plugins/my-plugin composer install

PHPUnit tests

wp-env run cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit

Pass flags with -- separator

wp-env run cli php -- --version

MySQL access

wp-env run mysql mysql -- --user=root --password=password wordpress


Available containers: `mysql`, `wordpress`, `cli`, `composer`, `phpmyadmin`.

wp-env run mysql mysql -- --user=root --password=password wordpress


可用容器：`mysql`、`wordpress`、`cli`、`composer`、`phpmyadmin`。

6. Manage the environment

6. 管理环境

wp-env stop                    # Stop and free ports
wp-env reset development       # Reset dev database (keeps test)
wp-env reset all               # Reset all databases
wp-env logs                    # Stream PHP/Docker logs
wp-env logs --no-watch         # Print logs and exit
wp-env status                  # Show URLs, ports, config
wp-env status --json           # Machine-readable status
wp-env cleanup                 # Remove containers/volumes (keep images)
wp-env destroy                 # Remove everything including images

wp-env stop                    # Stop and free ports
wp-env reset development       # Reset dev database (keeps test)
wp-env reset all               # Reset all databases
wp-env logs                    # Stream PHP/Docker logs
wp-env logs --no-watch         # Print logs and exit
wp-env status                  # Show URLs, ports, config
wp-env status --json           # Machine-readable status
wp-env cleanup                 # Remove containers/volumes (keep images)
wp-env destroy                 # Remove everything including images

7. Xdebug setup

7. Xdebug配置

wp-env start --xdebug          # Enable debug mode
wp-env start --xdebug=coverage # For code coverage
wp-env start                   # Disable Xdebug (restart without flag)

Modes:

debug

profile

trace

develop

coverage

IDE listens on port 9003. VS Code

launch.json

needs:

json

{
  "type": "php",
  "request": "launch",
  "name": "Listen for Xdebug",
  "port": 9003,
  "pathMappings": {
    "/var/www/html/wp-content/plugins/your-plugin": "${workspaceFolder}"
  }
}

wp-env start --xdebug          # Enable debug mode
wp-env start --xdebug=coverage # For code coverage
wp-env start                   # Disable Xdebug (restart without flag)

模式：

debug

、

profile

、

trace

、

develop

、

coverage

。

IDE监听端口为 9003。VS Code 的

launch.json

需要配置：

json

{
  "type": "php",
  "request": "launch",
  "name": "Listen for Xdebug",
  "port": 9003,
  "pathMappings": {
    "/var/www/html/wp-content/plugins/your-plugin": "${workspaceFolder}"
  }
}

8. Multisite

8. 多站点

json

{ "multisite": true, "plugins": ["."] }

json

{ "multisite": true, "plugins": ["."] }

Verification

验证步骤

```
wp-env status
```
shows running containers with correct ports
```
http://localhost:8888/wp-admin/
```
loads the WordPress admin
```
wp-env run cli wp plugin list
```
shows expected plugins
Plugin/theme under development appears in the WordPress admin
Database resets work:
```
wp-env reset development
```

```
wp-env status
```
显示运行中的容器及正确端口
```
http://localhost:8888/wp-admin/
```
可加载WordPress管理后台
```
wp-env run cli wp plugin list
```
显示预期的插件
开发中的插件/主题出现在WordPress管理后台
数据库重置功能正常：
```
wp-env reset development
```

Failure modes / debugging

故障排查

Symptom	Cause	Fix
"Cannot connect to Docker daemon"	Docker not running	Start Docker Desktop
"Port 8888 already in use"	Port conflict	Use `--auto-port` or set custom `port` in `.wp-env.json`
Plugin not appearing	Missing `Plugin Name:` header in main PHP file	Add standard plugin header comment
"Could not find a valid source"	Invalid source string in config	Use full ZIP URL for wp.org plugins, not bare slugs
Stale environment after source changes	Cached Docker volumes	`wp-env start --update` or `wp-env destroy && wp-env start`
White screen / PHP errors	Corrupted database	`wp-env reset all && wp-env start`
Override not taking effect	Wrong merge behavior	`plugins` / `themes` in override replace base arrays; only `config` / `mappings` merge
Tests environment not accessible	Wrong port	Test environment runs on port 8889 by default
Xdebug not connecting	IDE not listening or wrong port	Ensure IDE listens on port 9003 with correct `pathMappings`
npm global install permission error	Node installed to a system path	Use `nvm` , or install locally: `npm i -D @wordpress/env` and run via `npx wp-env`

症状	原因	解决方法
"Cannot connect to Docker daemon"	Docker未运行	启动Docker Desktop
"Port 8888 already in use"	端口冲突	使用 `--auto-port` 或在 `.wp-env.json` 中设置自定义 `port`
插件未显示	主PHP文件中缺少 `Plugin Name:` 头信息	添加标准插件头注释
"Could not find a valid source"	配置中的源字符串无效	对wp.org插件使用完整ZIP URL，而非裸别名
源码变更后环境未更新	Docker卷缓存	执行 `wp-env start --update` 或 `wp-env destroy && wp-env start`
白屏/PHP错误	数据库损坏	执行 `wp-env reset all && wp-env start`
覆盖配置未生效	合并行为不符合预期	覆盖配置中的 `plugins` / `themes` 会替换基础数组；仅 `config` / `mappings` 会合并
测试环境无法访问	端口错误	测试环境默认运行在8889端口
Xdebug无法连接	IDE未监听或端口错误	确保IDE在9003端口监听，并配置正确的 `pathMappings`
npm全局安装权限错误	Node安装在系统路径下	使用 `nvm` ，或本地安装： `npm i -D @wordpress/env` 并通过 `npx wp-env` 运行

Escalation

需升级处理的场景

Docker issues beyond wp-env scope (networking, disk space, WSL2 backend)
Custom Docker Compose configurations that conflict with wp-env
CI/CD pipeline integration requiring non-standard Docker setups
WordPress Playground runtime (
```
--runtime=playground
```
) is experimental and has limited feature parity

超出wp-env范围的Docker问题（网络、磁盘空间、WSL2后端）
与wp-env冲突的自定义Docker Compose配置
需要非标准Docker设置的CI/CD流水线集成
WordPress Playground运行时（
```
--runtime=playground
```
）属于实验性功能，功能不完全对等

wp-env

Original

Translation

@wordpress/env (wp-env)

@wordpress/env (wp-env)

When to use

适用场景

Inputs required

所需输入信息

Procedure

操作步骤

1. Install wp-env

1. 安装wp-env

Global (recommended)

Global (recommended)

Or project-local

Or project-local

Then use: npx wp-env start

Then use: npx wp-env start

2. Start the environment

2. 启动环境

3. Auto-detection (no config file)

3. 自动检测（无配置文件时）

4. Configure with .wp-env.json

4. 使用 .wp-env.json 配置

Source string formats (for core, plugins, themes, mappings)

源字符串格式（用于 core、plugins、themes、mappings）

Local overrides with .wp-env.override.json

使用 .wp-env.override.json 进行本地覆盖

5. Run commands in containers

5. 在容器中运行命令

WP-CLI commands

WP-CLI commands

Run commands in a specific directory

Run commands in a specific directory

PHPUnit tests

PHPUnit tests

Pass flags with -- separator

Pass flags with -- separator

MySQL access

MySQL access

6. Manage the environment

6. 管理环境

7. Xdebug setup

7. Xdebug配置

8. Multisite

8. 多站点

Verification

验证步骤

Failure modes / debugging

故障排查

Escalation

需升级处理的场景

References

参考资料

4. Configure with
`.wp-env.json`

4. 使用
`.wp-env.json`
配置

Source string formats (for
`core`
,
`plugins`
,
`themes`
,
`mappings`
)

源字符串格式（用于
`core`
、
`plugins`
、
`themes`
、
`mappings`
）

Local overrides with
`.wp-env.override.json`

使用
`.wp-env.override.json`
进行本地覆盖