wp-cli

wp-cli

以终端为先的 WordPress 运维方式。处理批量任务时比 wp-admin 更安全，支持脚本化，适用于 SSH，不会在更新 1 万行数据时超时。

只有检查命令和 wp db export（会创建备份）可以在不提示的情况下运行。所有会修改数据的命令——search-replace、db import、db reset、安装插件或主题，以及写入用户和文章——运行前都会提示确认。这种刻意设置的阻碍是有意为之：此技能经常会指向生产环境。

参考文件位于 ${CLAUDE_SKILL_DIR}/references/。

不适用场景

• 内容编辑人员能在管理界面中 10 秒内完成的一次性编辑。对单行内容而言，CLI 过于复杂，也容易出错。
• 涉及数百万行数据的转换——WP 的 ORM 会很慢；可考虑使用带有显式事务的直接 SQL 迁移。
• 需要在 WordPress 插件的钩子生命周期内运行的操作（例如 REST 验证、自定义文章类型注册）——这属于 PHP 代码，而不是 CLI。
• 没有当前备份时执行破坏性命令。wp db reset、wp db clean、批量删除——务必先创建快照。

执行前检查

执行任何操作前，务必先验证：

wp --version                  # wp-cli is installed
wp core is-installed          # WordPress is actually set up at this path
wp core version               # which WP version

如果当前目录不是 WordPress 根目录，请传入 --path=/path/to/wordpress，或先切换到该目录。在远程主机上，使用 --ssh=user@host/path 或已配置的别名（参见远程执行）。

安全模式

执行破坏性操作前先备份

# Database snapshot
wp db export backup-$(date +%Y%m%d-%H%M%S).sql

# Full site snapshot (db + content)
tar -czf site-backup-$(date +%Y%m%d-%H%M%S).tar.gz wp-content/ backup-*.sql

有试运行选项时先试运行

wp plugin update --all --dry-run
wp search-replace 'old.com' 'new.com' --dry-run

危险命令——明确确认

如果没有备份，这些操作无法撤销。运行前请向用户确认：

• wp db reset — 删除所有表
• wp db clean — 删除所有匹配当前 $table_prefix 的表
• wp site delete（多站点）— 删除一个站点及其内容
• 不带 --reassign 的 wp user delete — 使该用户的文章成为孤立内容（这些文章也会被删除）。务必传入 --reassign=<new_author_id>，先重新分配其内容。设置此标志是因为孤立内容几乎从来不是你想要的结果——用户的文章才是机构记录，而不是用户行。
• wp post delete $(wp post list --format=ids) 及类似的批量删除管道——如果筛选条件有误，会悄无声息地将整个站点变成空白页面。

性能标志

--format=json              # machine-readable
--format=csv               # spreadsheet import
--format=ids               # space-separated IDs, for piping
--fields=ID,post_title     # return only what you need
--skip-plugins             # bypass plugin load (fast, may break plugin-dependent commands)
--skip-themes              # bypass theme load
--quiet                    # suppress info output

--skip-plugins 是一把手术刀：它能让 wp db export 瞬间完成，但会破坏依赖插件钩子的命令（例如 ACF 导出器、由插件注册的自定义分类法）。

命令目录

完整的标志文档和注意事项见 references/commands.md。类别如下：

类别	前缀	典型用途
数据库	wp db	导出、导入、查询、优化、搜索替换
核心	wp core	安装、更新、验证校验和、版本
插件	wp plugin	列出、安装、启用、更新、删除
主题	wp theme	列出、安装、启用、更新、删除、theme mod
用户	wp user	创建、列出、删除（--reassign）、更新、角色、生成
文章 / 页面	wp post	列出、创建、更新、删除、生成、post term
评论	wp comment	列出、批准、标记为垃圾评论、移至回收站、删除
选项	wp option	获取、更新、删除、列出；嵌套值可用 pluck/patch
缓存	wp cache / wp transient	清空、删除、设置、列出
Cron	wp cron	列出/运行/安排/删除事件，Cron 测试
配置	wp config	创建、获取、设置、轮换盐值
多站点	wp site	列出、创建、删除、清空、启用/存档

工作流

完整的分步工作流位于 references/ 中，并按任务拆分——只加载用户正在端到端执行的那一项：

工作流	文件
站点迁移（本地 → 生产环境）+ 搜索替换	references/examples-migration.md
插件更新、回滚、调试、数据库维护	references/examples-maintenance.md
用户审计、清理、安全轮换密码	references/examples-users.md
从 CSV 批量导入内容	references/examples-content.md
多站点 / 网络操作	references/examples-multisite.md

远程执行

临时 SSH

ssh [email protected] "cd /var/www/html && wp plugin list"

已配置的别名（推荐）

在 ~/.wp-cli/config.yml 中定义一次别名：

@prod:
  ssh: [email protected]/var/www/html
@staging:
  ssh: [email protected]/var/www/staging

然后：

wp @prod plugin list
wp @staging db export

别名优于临时 SSH，因为它们能与每个 wp-cli 标志组合使用（wp @prod --dry-run search-replace ...），也不会引发 shell 引号问题。

常见错误

错误	原因	修复方法
The site you have requested is not installed	当前目录不在 WordPress 根目录 / 缺少 wp-config.php	cd 到根目录，或使用 --path=/path/to/wordpress
MySQL connection failed	凭据错误或 MySQL 已停止	检查 wp-config.php，确认 MySQL 正在运行
Error: Can't select database	数据库不存在	wp db create
PHP Fatal error: Allowed memory size exhausted	操作规模过大或插件占用资源过多	php -d memory_limit=512M $(which wp) db export
This does not seem to be a WordPress installation	未找到 WP 文件	检查目录；确认 WP 确实已安装
The \guid` column is often used ... but should not be updated`	预期中的警告	使用 --skip-columns=guid 可抑制此警告；GUID 是永久 ID，不是 URL

反模式 — wp-cli 不适用的场景

• 在 shell 中用 xargs 或 for 循环处理数百万行。 每次调用 wp 都会引导启动 WordPress；迭代 100 万次需要数天。建议改用单条适当的 SQL 语句执行 wp db query，或使用 PHP 端的批处理任务。
• 对超过个人博客规模的序列化数据使用 wp search-replace，却不加 --precise。 --precise 速度较慢，但能正确处理 PHP 序列化字符串；不加此选项会导致序列化数组在无提示的情况下损坏。
• 验证和领域逻辑。 如果逻辑属于 WP 插件的钩子生命周期，就在那里执行。wp-cli 用于运维工作，而非业务规则。
• 在 shell 历史记录中留下包含凭据的命令。 使用 --user_pass=... 的 wp user create 会泄露密码。通过管道传入密码，或让 wp-cli 提示输入。

最佳实践

1. 始终先在预发布环境测试。 切勿在生产环境运行未经测试的命令。
2. 条件允许时，将 wp-config.php 的更改纳入版本控制（排除机密信息）。
3. 仔细阅读输出。 wp-cli 的警告往往是数据丢失的前兆。
4. 及时记录不明显的工作流——例如迁移、多站点转换；未来的你不会记得当时用了哪些标志。
5. 通过管道传递给 jq 或其他脚本时，使用 --format=json。 默认的人类可读格式会逐渐失效。
6. 重大更改后进行验证——加载首页、检查管理界面、测试关键路径。
7. 保持 wp-cli 为最新版本：wp cli update（仅适用于 Phar 安装——Homebrew 和 Composer 安装需通过各自的包管理器更新）。

参考资料

• references/commands.md — 按类别整理的命令和标志详细参考
• 工作流指南（按需加载）：
  • references/examples-migration.md — 迁移和搜索替换
  • references/examples-maintenance.md — 插件更新、调试、数据库维护
  • references/examples-users.md — 用户审计和清理
  • references/examples-content.md — CSV 内容导入
  • references/examples-multisite.md — 多站点操作
• 上游文档：https://developer.wordpress.org/cli/commands/