wp-env

@wordpress/env（wp-env）

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

适用场景

• 用户要求搭建 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 后备方案，而不是第三种选择。它会用 SQLite 替代 MySQL，并移除 wp-env run 和独立的测试环境，而这些正是选择 wp-env 的主要原因。若要在没有 wp-env 配置的情况下快速运行无 Docker 的 WordPress，请直接使用 wp-playground 技能。

所需输入

1. Docker 状态——确认 Docker 已安装并正在运行：docker info
2. Node.js 版本——必须 >= 18.12.0：node -v
3. 项目类型——插件、主题或完整站点（检查 .wp-env.json、插件标头或 style.css 主题标头）
4. 现有配置——如果存在，读取 .wp-env.json 和 .wp-env.override.json

操作步骤

1. 安装 wp-env

# Global (recommended)
npm -g install @wordpress/env

# Or project-local
npm i @wordpress/env --save-dev
# Then use: npx wp-env start

2. 启动环境

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. 自动检测（无配置文件时）

如果不存在 .wp-env.json，wp-env 会扫描当前目录：

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

4. 使用 .wp-env.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%/"
  }
}

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

格式	示例
本地路径	"."、"./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 插件/主题 slug（如 "akismet" 这样的裸名称）不起作用。请使用完整的 ZIP URL。

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

在 .wp-env.json 旁边创建 .wp-env.override.json，用于个人设置（已加入 gitignore）。只有 config 和 mappings 会进行合并——其他所有字段（包括 plugins 和 themes 数组）都会完全替换基础配置。

5. 在容器中运行命令

# 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

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

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

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)

模式：debug、profile、trace、develop、coverage。

IDE 在端口 9003 上监听。VS Code 的 launch.json 需要：

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

8. 多站点

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

验证

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

故障模式／调试

症状	原因	修复方法
“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”	配置中的 source 字符串无效	对于 wp.org 插件，请使用完整 ZIP URL，而不是裸 slug
更改 source 后环境未更新	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 运行

升级处理

• 超出 wp-env 范围的 Docker 问题（网络、磁盘空间、WSL2 后端）
• 与 wp-env 冲突的自定义 Docker Compose 配置
• 需要非标准 Docker 设置的 CI/CD 流水线集成
• WordPress Playground 运行时（--runtime=playground）仍处于实验阶段，功能兼容性有限

参考资料

• 官方文档
• 入门指南
• 源代码