WordPress WP-CLI 命令行工具完全指南：从安装配置到自动化运维实战

Table of Contents

引言：为什么每个WordPress开发者都应该掌握WP-CLI

如果你管理过WordPress站点，一定经历过这样的痛苦：每次要更新插件就要登录后台、点击十几个按钮、等待页面刷新；每次要批量修改文章作者就要装一个新插件；每次要在多个环境之间同步配置就要手动导出导入。这些重复且耗时的操作，其实都可以用WP-CLI在命令行里几秒钟完成。

WP-CLI（WordPress Command Line Interface）是WordPress官方维护的命令行工具，它让你能够通过命令行完成几乎所有WordPress后台能做的事情，而且更适合自动化、批量处理和远程服务器管理。无论是日常运维、CI/CD流水线集成，还是批量站点管理，WP-CLI都是必备技能。本文将从安装配置讲起，系统讲解WP-CLI的常用命令、高级用法和实战技巧。

WP-CLI 安装与环境配置

系统要求与安装方式

WP-CLI是一个PHAR（PHP Archive）文件，运行它只需要PHP 5.6+环境（推荐PHP 7.4+）。安装方式非常简单：


1
2
3
4
5
6
7
8
9
10
11
# 下载 WP-CLI 的 PHAR 文件

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar



# 添加可执行权限

chmod +x wp-cli.phar



# 移动到 PATH 中，使命令全局可用

sudo mv wp-cli.phar /usr/local/bin/wp



# 验证安装

wp --info

验证安装时，你应该看到类似下面的输出，确认PHP版本、WP-CLI版本等信息：


1
2
3
4
5
6
OS:     Linux 5.15.0-138-generic

Shell:  /bin/bash

PHP binary: /usr/bin/php8.1

PHP version:    8.1.2

WP-CLI root dir:    phar://wp-cli.phar

WP-CLI version:    2.7.1

通过Composer安装

如果你的项目已经使用Composer管理依赖，也可以将WP-CLI作为项目依赖安装：


1
2
3
4
composer require wp-cli/wp-cli-bundle



# 然后通过 vendor/bin/wp 调用

./vendor/bin/wp --info

Bash自动补全配置

WP-CLI提供了Bash补全脚本，能大幅提升命令行效率。配置方法：


1
2
3
4
5
6
7
8
# 下载补全脚本

curl -O https://raw.githubusercontent.com/wp-cli/wp-cli/main/utils/wp-completion.bash



# 加载到当前 shell

source wp-completion.bash



# 持久化到 .bashrc

echo "source ~/wp-completion.bash" >> ~/.bashrc

配置完成后，输入

然后按Tab键就能自动补全所有子命令。

核心命令体系：掌握常用命令

WP-CLI的命令采用层级结构，主命令下有子命令，子命令下还可以有参数。掌握命令体系的最佳方式是善用

wp help

和

--help

参数：


1
2
3
4
5
6
7
8
# 查看所有顶级命令

wp help



# 查看某个命令的子命令和用法

wp post --help



# 查看子命令的详细参数

wp post create --help

站点状态与配置管理

WP-CLI提供了快捷命令查看站点核心信息，这在排查环境问题时非常有用：


1
2
3
4
5
6
7
8
9
10
11
12
13
# 查看站点核心信息（WordPress版本、数据库信息、活跃插件等）

wp core version

wp core is-installed



# 查看所有配置选项

wp option list



# 获取/设置单个选项

wp option get siteurl

wp option update siteurl 'https://example.com'



# 搜索选项

wp option list --search="*cache*" --fields=option_name,option_value

插件与主题管理

这是WP-CLI最常用的功能之一。批量安装、启用、禁用插件一行命令搞定，比后台点击快得多：


1
2
3
4
5
6
7
8
9
10
11
12
# 插件管理

wp plugin install wordpress-seo --activate

wp plugin install contact-form-7 --version=5.6.4 --force

wp plugin list --status=active --fields=name,version

wp plugin deactivate --all            # 禁用所有插件（排查冲突时常用）

wp plugin uninstall akismet --skip-delete    # 卸载但不删除文件



# 主题管理

wp theme install twentytwentytwo --activate

wp theme list --status=active

wp theme mod list                     # 查看主题自定义设置

wp theme mod set header_textcolor '000000'

一个特别实用的技巧是：在排查插件冲突时，先用

1	wp plugin deactivate --all

禁用所有插件，再逐个启用，能快速定位问题插件。这比在后台一个个点击快10倍以上。

用户与权限管理

WP-CLI对用户管理的支持非常完善，可以批量创建、修改用户，也能精确控制角色权限：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 创建管理员用户

wp user create admin admin@example.com --role=administrator --user_pass=StrongPass123!



# 批量列出用户

wp user list --fields=ID,user_login,user_email,roles --format=table



# 修改用户密码

wp user update 5 --user_pass=NewPassword456!



# 修改用户角色

wp user update 3 --role=editor



# 查看所有角色及其权限

wp cap list administrator

wp cap add editor manage_options   # 给editor添加自定义权限

wp cap remove subscriber read      # 移除权限（慎用）

内容操作：文章、分类与媒体的命令行管理

文章与页面管理

WP-CLI可以高效地批量管理文章。无论是批量修改作者、批量删除垃圾文章，还是从CSV导入大量文章，都能轻松完成：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 创建文章

wp post create --post_type=post --post_title='测试文章' --post_content='正文内容' --post_status=publish



# 列出最近10篇文章

wp post list --post_type=post --posts_per_page=10 --fields=ID,post_title,post_date,post_status



# 批量修改文章作者

wp post list --post_type=post --author=2 --field=ID | xargs -I {} wp post update {} --post_author=1



# 批量将草稿发布

wp post list --post_status=draft --field=ID | xargs -I {} wp post update {} --post_status=publish



# 从CSV导入文章

wp post generate --count=100 --post_type=post --post_status=draft



# 删除某作者的所有文章

wp post delete $(wp post list --author=3 --field=ID)

分类与标签管理


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 创建分类（带父分类）

wp term create category '技术教程' --slug=tutorials --parent=5



# 列出所有分类及文章数量

wp term list category --fields=term_id,name,slug,count --format=table



# 批量给文章添加标签

wp post term add 42 post_tag 'PHP' 'WordPress' '教程'



# 重命名分类

wp term update 15 --name='新分类名'



# 合并两个分类（把分类B的文章移到分类A，删除B）

wp post list --category=category-b --field=ID | xargs -I {} wp post term remove {} category category-b

wp term delete category category-b

媒体库管理

WP-CLI对媒体的处理非常强大，特别是

1	media regenerate

命令，是每个WordPress运维人员的必备工具：


1
2
3
4
5
6
7
8
9
10
11
# 重新生成所有缩略图（更换主题或插件后必做）

wp media regenerate --yes



# 只重新生成指定文章的图片

wp media regenerate $(wp post list --post_type=attachment --field=ID --posts_per_page=50)



# 从URL导入图片并附加到文章

wp media import https://images.unsplash.com/photo-1551288049-bebda4e38f71 --post_id=42 --title='数据仪表盘' --featured_image



# 批量从目录导入图片

wp media import /path/to/images/*.jpg --post_id=42

一个常见场景：当你修改了主题或插件定义的图片尺寸后，旧图片不会自动应用新尺寸，这时候就需要

1	wp media regenerate

来重新生成所有缩略图。对于图片多的站点，建议加

1	--skip-delete

参数避免删除原图。

数据库操作与备份还原

导出与导入数据库

WP-CLI提供了比phpMyAdmin更安全、更可控的数据库导出导入功能：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 导出整个数据库（包含所有表）

wp db export backup-$(date +%Y%m%d).sql



# 导出指定表（节省空间，常用于只备份文章）

wp db export --tables=wp_posts,wp_postmeta posts-backup.sql



# 导入数据库

wp db import backup-20260725.sql



# 优化数据库表

wp db optimize



# 修复数据库表

wp db repair



# 查询数据库

wp db query "SELECT ID, post_title FROM wp_posts WHERE post_status='publish' LIMIT 5;"

搜索替换（迁移站点必备）

这是WP-CLI最强大的功能之一。注意：永远不要用SQL直接搜索替换WordPress数据库，因为WordPress会序列化数据，直接替换会破坏序列化结构。WP-CLI的

1	search-replace

正确处理了序列化：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 将旧域名替换为新域名

wp search-replace 'http://old-site.com' 'https://new-site.com'



# 指定表执行（更快）

wp search-replace 'http://old-site.com' 'https://new-site.com' wp_options wp_posts wp_postmeta



# 预演模式：只显示会修改什么，不真正修改

wp search-replace 'old' 'new' --dry-run



# 导出修改后的SQL（不直接写库）

wp search-replace 'old' 'new' --export=migration.sql



# 使用正则

wp search-replace 'foo[a-z]+bar' 'replacement' --regex

参数

用途

使用场景

--dry-run

预演，不真正修改

迁移前验证修改范围

--export

导出修改SQL到文件

在测试环境准备迁移脚本

--regex

使用正则匹配

复杂模式的批量替换

1	--skip-columns=guid

跳过指定列

guid列不应被替换

--precise

精确匹配（更慢）

处理序列化数据

高级用法：脚本化与自动化

WP-CLI 配置文件

WP-CLI支持

1	wp-cli.yml

配置文件，可以预先定义常用参数，避免每次都输入长命令。在站点根目录创建：


1
2
3
4
5
6
7
8
9
10
11
12
# wp-cli.yml 示例

path: /var/www/html

apache_modules:

  - mod_rewrite



# 定义命令别名，方便切换不同环境

@production:

  ssh: root@prod-server.com/var/www/html

@staging:

  ssh: root@staging-server.com/var/www/html

@local:

  path: /var/www/html

配置好别名后，可以用

1	wp @production plugin list

直接操作生产服务器，无需每次输入SSH路径。

执行PHP代码

WP-CLI的

eval

和

eval-file

命令可以在WordPress环境中执行任意PHP代码，这对于调试和批量操作非常有用：


1
2
3
4
5
6
7
8
9
10
11
12
13
# 在WordPress环境中执行PHP

wp eval 'echo get_option("siteurl");'



# 执行更复杂的逻辑

wp eval '

$posts = get_posts(["numberposts" => 5, "post_status" => "publish"]);

foreach ($posts as $p) {

    echo $p->ID . ": " . $p->post_title . "\n";

}

'



# 从文件执行更长的脚本

wp eval-file /path/to/migration-script.php

结合Shell脚本实现自动化任务

WP-CLI的命令行输出可以轻松管道到其他工具，下面是几个实用的自动化脚本示例：

示例1：每日站点健康检查


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#!/bin/bash

# daily-health-check.sh



DATE=$(date +%Y%m%d)

LOG="/var/log/wp-health-$DATE.log"



echo "=== WordPress 站点健康检查 $DATE ===" | tee -a $LOG

wp core version | tee -a $LOG

wp plugin list --status=active --fields=name,version --format=table | tee -a $LOG

wp db size --human-readable | tee -a $LOG



# 检查待更新

UPDATES=$(wp plugin list --update-available --field=name)

if [ -n "$UPDATES" ]; then

    echo "警告：以下插件有更新可用：" | tee -a $LOG

    echo "$UPDATES" | tee -a $LOG

fi

示例2：批量迁移多站点配置


1
2
3
4
5
6
7
8
9
10
11
12
13
#!/bin/bash

# 批量迁移所有子站点域名



OLD_DOMAIN="old.example.com"

NEW_DOMAIN="new.example.com"



# 获取所有子站点ID

SITE_IDS=$(wp site list --field=blog_id)



for id in $SITE_IDS; do

    echo "处理站点 $id..."

    wp search-replace $OLD_DOMAIN $NEW_DOMAIN --url=$(wp site url $id) --skip-columns=guid

done

使用WP-Cron调度任务

WP-CLI提供了独立于WordPress本身的Cron管理能力，可以触发或模拟Cron任务：


1
2
3
4
5
6
7
8
9
10
11
# 查看所有调度任务

wp cron event list --fields=hook,next_run_relative,recurrence



# 手动触发某个Cron任务

wp cron event run wp_version_check



# 运行所有到期的Cron任务

wp cron event run --due-now



# 测试某个定时任务（不影响调度）

wp cron event run my_custom_hook

常见运维场景实战

场景1：从备份完整恢复站点

站点出问题后需要快速恢复，WP-CLI能让整个流程标准化：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#!/bin/bash

# restore-site.sh - 站点恢复脚本



BACKUP_DATE=$1

BACKUP_DIR="/backups/$BACKUP_DATE"

WWW_ROOT="/var/www/html"



# 1. 恢复文件

rsync -avz $BACKUP_DIR/files/ $WWW_ROOT/



# 2. 恢复数据库

wp db import $BACKUP_DIR/db.sql --path=$WWW_ROOT



# 3. 更新域名（如果迁移到新域名）

wp search-replace 'https://old.example.com' 'https://new.example.com' --skip-columns=guid



# 4. 重新生成缩略图

wp media regenerate --yes



# 5. 刷新固定链接

wp rewrite flush



# 6. 清除缓存

wp cache flush

wp rewrite flush



echo "站点恢复完成"

场景2：CI/CD部署集成

在GitLab CI或GitHub Actions中，WP-CLI常用于部署后自动化配置：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# .github/workflows/deploy.yml 片段

- name: Deploy WordPress

  run: |

    # 拉取代码

    rsync -avz --delete ./ $WWW_ROOT/

    

    # 维护模式

    wp maintenance-mode activate --path=$WWW_ROOT

    

    # 更新数据库结构

    wp core update-db --path=$WWW_ROOT

    

    # 处理潜在插件冲突

    wp plugin deactivate problematic-plugin --path=$WWW_ROOT

    

    # 清除缓存

    wp cache flush --path=$WWW_ROOT

    wp rewrite flush --path=$WWW_ROOT

    

    # 关闭维护模式

    wp maintenance-mode deactivate --path=$WWW_ROOT

场景3：性能问题排查

当站点变慢时，WP-CLI能快速定位问题：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 检查数据库表大小，定位膨胀表

wp db size --tables --human-readable



# 查看修订版本数量（过多会拖慢数据库）

wp post list --post_type=revision --field=ID | wc -l



# 批量删除旧修订版本

wp post delete $(wp post list --post_type=revision --field=ID --posts_per_page=1000) --force



# 检查自动草稿和回收站

wp post list --post_status=auto-draft --field=ID

wp post list --post_status=trash --field=ID



# 清除transient缓存（过期数据堆积）

wp transient delete --expired

WP-CLI 最佳实践与注意事项

安全第一

使用WP-CLI时必须注意安全，特别是生产环境：

永远先备份：执行任何修改操作前先
1
wp db export
使用
1
--dry-run

：search-replace等命令先预演
限制SSH访问：通过SSH使用WP-CLI时，确保密钥认证和防火墙配置
避免明文密码：使用
1
--prompt

让WP-CLI交互式输入密码，或用

1
WP_CLI_PASSWORD

环境变量
正确设置文件权限：确保
1
wp-cli.yml

不被公开访问

性能优化

处理大型站点时，WP-CLI有一些性能技巧：

使用
1
--fields

限制输出列，减少内存占用
批量操作时用
1
xargs

并行处理：

1
wp post list --field=ID | xargs -P 4 -I {} wp post update {} ...
禁用不必要的钩子：
1
--skip-themes --skip-plugins

能跳过主题和插件加载，大幅提升速度
对于特别大的数据库操作，用
1
--export

生成SQL文件再通过

1
mysql

命令导入，比直接执行更快

常见错误与排查

错误信息

原因

解决方案

Error: This does not seem to be a WordPress installation.

使用

1	--path=/var/www/html

指定路径

Error: YIKES! It looks like you’re running this as root.

以root运行警告

加

1	--allow-root

，或切换到www用户

PHP Fatal error: Allowed memory size exhausted

内存不足

增大

1	WP_CLI_PHP_MEMORY_LIMIT

或

1	--memory-limit

Error: Database connection error

wp-config.php配置错误

检查

1	wp config get DB_HOST

等配置

总结

WP-CLI是WordPress生态中最被低估但最强大的工具之一。它把WordPress从”必须用浏览器管理”的框架，变成了真正可以脚本化、自动化的现代Web平台。本文从安装、常用命令、数据库操作、自动化脚本到实战场景进行了系统讲解，希望能帮助你把日常繁琐的WordPress运维工作转化为高效的命令行操作。

掌握WP-CLI的核心收益在于：将重复的手动操作沉淀为可复用的脚本。无论是日常的备份、部署，还是偶尔的故障恢复、站点迁移，一旦写成脚本，就能稳定、可追溯地执行无数次。这种从”手工操作”到”代码化运维”的转变，是每个WordPress开发者进阶的必经之路。

建议从今天开始，把你在WordPress后台最常做的3个操作，尝试用WP-CLI命令重写一次，你会立刻感受到效率提升的魅力。