正文

WP-CLI 排障手记，从环境检测到回滚修复，七个高频坑的外科手术式处理实录

机房驻场手记
机房驻场手记 V管理员 /6阅读/3评论
0821
文章最后更新时间2026年08月21日，若文章内容或图片失效，请留言反馈！

安装环境检测不通过——不是缺扩展，是“假性”缺失

报错现象： 执行 wp core install 时，终端直接抛出 Error: Required PHP extension: mysqli 或 Error: The PHP extension "curl" is missing，但用 php -m 检查，扩展明明已经安装。

原因分析： 这是经典的“CLI 与 Web 环境 PHP 配置不一致”问题，你的 Web 服务器（Nginx/Apache）用的是 FPM 或模块方式加载的 PHP，而 WP-CLI 默认调用的 php 命令指向了另一个二进制文件（比如系统自带的 PHP 7.4，而 Web 环境是 PHP 8.2）。php.ini 路径不同，导致 CLI 模式未加载扩展目录。

WP-CLI 排障手记，从环境检测到回滚修复，七个高频坑的外科手术式处理实录

WP-CLI 排障手记，从环境检测到回滚修复，七个高频坑的外科手术式处理实录

解决步骤：

  1. 确认 WP-CLI 实际使用的 PHP 版本：wp --info，查看 PHP binary 和 PHP version。
  2. 若版本不对,指定绝对路径调用，/usr/local/php8.2/bin/php wp core install。
  3. 若版本对但扩展缺失,编辑对应 PHP 版本的 php.ini（通过 php --ini 找到路径），在 extension_dir 处填写正确的扩展目录，并取消 extension=mysqli 和 extension=curl 前的分号注释。
  4. 如果服务器用宝塔或面板,直接在面板的“PHP 扩展”中安装对应扩展，然后重启 PHP-FPM。切记： 不要改错 php.ini，用 php -i | grep php.ini 确认加载路径。

数据库连接错误——密码含特殊字符的“引号陷阱”

报报错现象： wp db check 返回 ERROR 1045 (28000): Access denied for user 'wp_user'@'localhost'，但用 Navicat 或 宝塔 数据库管理工具却可以正常登录。

原因分析： WP-CLI 在读取 wp-config.php 时，如果你的数据库密码包含 、、 或反斜杠，PHP 的 parse_ini_file 或直接 define 常量时会把特殊字符当成语法解析，导致密码被截断。

解决步骤：

  1. 打开 wp-config.php，检查 DB_PASSWORD 定义：define('DB_PASSWORD', 'abc$123'); 这里的 $123 会被 PHP 视为变量名，需要改为 define('DB_PASSWORD', 'abc\$123');（用反斜杠转义）。
  2. 更稳妥的解决方案：在 wp-config.php 中添加 define('DB_HOST', 'localhost:/tmp/mysql.sock');（如果是 socket 连接），或者改用 IP 连接：define('DB_HOST', '127.0.0.1:3306');，避免本地 socket 权限问题。
  3. 若密码极其复杂,建议直接在命令行用环境变量绕过：DB_PASSWORD='你的真实密码' wp db check，这样 WP-CLI 会优先读取环境变量。

500 内部服务器错误——是“权限”而不是“代码”

报错现象： 前端浏览器显示 500 Internal Server Error，但 wp core is-installed 能运行，后台也进不去，Nginx 错误日志显示 Primary script unknown 或 Permission denied。

原因分析： 这不是 PHP 语法错误，而是 WordPress 目录或文件的 所有权 和 权限 不对，常见于使用 tar 包解压或从 Windows 上传代码后，www-data 用户无法读取 index.php，或者 wp-content 无法写入。

解决步骤：

  1. 进入站点根目录,执行：chown -R www-data:www-data /var/www/html（Web 服务器用 nginx 则用户是 www-data，用 apache 则可能是 daemon）。
  2. 设置标准权限：find /var/www/html -type d -exec chmod 755 {} \; 和 find /var/www/html -type f -exec chmod 644 {} \;。
  3. 重点检查 wp-config.php 是否可读：ls -la wp-config.php，若权限为 600 也会导致 500（PHP-FPM 进程无法读取）。
  4. 如果还是 500，用 wp debug 命令开启调试：在 wp-config.php 中定义 define('WP_DEBUG', true); define('WP_DEBUG_LOG', true);，然后再次访问，查看 wp-content/debug.log 具体报错行。

白屏死机（WSOD）—— memory limit 压垮最后稻草

报错现象： 页面完全空白，无任何输出，wp plugin list 正常，但访问任意页面都白屏，查看 PHP 错误日志无记录。

原因分析： 最常见的是 PHP 内存耗尽，尤其当插件或主题加载过多数据时，WP-CLI 默认分配 256M，但 Web 环境被限制为 128M，另一种情况是插件或主题代码中使用了不兼容的 PHP 8+ 特性，导致 fatal error，但错误报告被关闭。

解决步骤：

  1. 用 WP-CLI 临时提升内存：wp --define=WP_MEMORY_LIMIT=512M eval 'echo ini_get("memory_limit");' 查看当前限制，如果太低，直接在 wp-config.php 添加：define('WP_MEMORY_LIMIT', '512M'); 和 define('WP_MAX_MEMORY_LIMIT', '512M');。
  2. 如果白屏发生在激活某个插件后,用命令强制禁用所有插件：wp plugin deactivate --all，然后依次启用排查。
  3. 若主题导致问题：wp theme activate twentytwentyfour 切换到默认主题。
  4. 最后用 wp db query "SELECT * FROM wp_options WHERE option_name='active_plugins';" 检查序列化数据是否损坏，若损坏则手动清空 active_plugins 字段为 a:0:{}。

插件冲突导致异常——钩子顺序混乱

报错现象： 插件功能异常，比如购物车不刷新、菜单消失、或者 REST API 返回 403。wp plugin list 显示全部启用，但页面行为怪异。

原因分析： 最常见的不是插件代码错误，而是两个插件同时挂载了同一个 AJAX 动作或 REST 路由，导致优先级高的插件覆盖了另一个的返回值，也可能是一个插件调用了 exit() 或 die()，中断了 WordPress 主进程。

解决步骤：

  1. 定位冲突范围：先关闭所有插件，保留 WooCommerce（如果是电商站），用 wp plugin deactivate --all && wp plugin activate woocommerce。
  2. 采用“二分法”激活：wp plugin activate 一次性激活一半插件，然后测试页面，逐步缩小范围。
  3. 若确定是 AJAX 冲突，用 wp eval 'print_r($wp_filter["wp_ajax_my_action"]);' 查看钩子列表，检查哪个插件注册了两个回调。
  4. 如果插件使用 register_rest_route 冲突，用 wp eval 'print_r(array_keys(WP_REST_Server::get_instance()->get_routes()));' 查看路由被谁覆盖，然后临时注释掉某个插件的 add_action 行。

自动更新失败回滚——数据库残留“半成品”

报错现象： 后台点击“更新 WordPress 到 6.5”，页面提示更新失败，并自动回滚，但之后 wp core version 显示 6.3，而 wp db query "SELECT * FROM wp_options WHERE option_name='db_version';" 显示 6.4 的数据库版本号，造成前后台数据不一致。

原因分析： WordPress 更新过程中，先更新文件，再执行数据库升级脚本，如果文件下载不完整或权限不足，数据库升级脚本只执行了一半，回滚只恢复了文件，却没恢复数据库选项。

解决步骤：

  1. 手动刷新数据库版本号：wp option update db_version 57164（这个数字是对应 6.3 的数据库版本，可去官网查询）。
  2. 强制修复文件：用 wp core download --version=6.3 --force 覆盖式重新下载核心文件。
  3. 重新执行数据库升级：wp core update-db，它会检查并补全缺失的数据库表。
  4. 如果仍有残留,用 wp db query "DELETE FROM wp_options WHERE option_name='auto_update_core_failed';" 清除失败标记，并关闭自动更新：wp option update auto_update_core 'disabled'。

登录页面重定向循环——缓存与 cookie 域名错位

报错现象： 访问 /wp-login.php 时浏览器提示“此页面无法正确重定向”，或者瞬间跳转到 /wp-admin/ 又弹回登录页。wp user list 能查到账号，但就是无法登录。

原因分析： 通常是站点地址（Site URL）和首页地址（Home URL）不一致，或者 WordPress 缓存插件（如 W3 Total Cache）保存了错误的页面跳转规则，如果启用了 HTTP 到 HTTPS 强制跳转，但代理层未处理 X-Forwarded-Proto，也会导致 loop。

解决步骤：

  1. 用 WP-CLI 直接修正地址：wp option update home 'https://你的域名' 和 wp option update siteurl 'https://你的域名'（注意带不带 www 要一致）。
  2. 若启用了 Redis 或 Memcached，清空缓存：wp cache flush。
  3. 对于缓存插件生成的 .htaccess 或 Nginx 配置，删除 wp-content/cache/ 目录下的所有文件，然后用 wp rewrite flush 重建重写规则。
  4. 如果是反代导致的 HTTPS 识别问题，在 wp-config.php 的 ABSPATH 之前添加： 
    if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] == 'https') {
 $_SERVER['HTTPS'] = 'on';
}
  5. 最后检查 wp_options 中的 _transient_wpseo_redirect 这类插件临时字段，用 wp transient delete --all 清理所有瞬态数据。