DocsWP — WordPress Help

故障排除指南

在您开始针对 GitHubGitHub GitHub 是一个提供 Git 仓库在线实现的网站，其他开发者可以轻松地共享、复制和修改这些仓库。公共仓库可免费托管，私有仓库则需要付费订阅。GitHub 引入了“拉取请求”的概念，贡献者在分支中完成的代码更改可以先由仓库所有者进行审查和讨论，然后再合并。 https://github.com/ 仓库报告新问题之前，请务必检查您的本地安装，因为某些设置通常可能会导致您的 WP-CLIWP-CLI WP-CLI 是 WordPress 的命令行界面，用于以编程方式执行管理和开发任务。项目页面是 http://wp-cli.org/ https://make.wordpress.org/cli/ 命令产生意外结果。

如何获取有关 WP-CLI 安装的更详细信息？

WP-CLI 提供了 wp --info 命令，可提供大量有关 WP-CLI 安装环境的信息。输出将告诉您，
* 您使用的操作系统和 shell
* 用于运行 WP-CLI 的 PHPPHP PHP（PHP：超文本预处理器的递归缩写）是一种广泛使用的开源通用脚本语言，特别适用于 Web 开发，并且可以嵌入 HTML 中。 https://www.php.net/manual/en/index.php 二进制文件
* 使用的 PHP 版本
* WP-CLI 根目录的位置
* WP-CLI vendor 目录的位置
* 当前使用的 WP-CLI 二进制文件（phar 路径）
* WP-CLI 软件包的存储位置
* WP-CLI 全局配置文件和项目配置文件的位置，以及
* 使用的 WP-CLI 版本。

在开始调试问题之前，我应该做什么？

开始调试问题之前，请确保您使用的是最新版本的 WP-CLI。最新版本可能已经解决了您遇到的问题。wp cli update 命令会升级您的 WP-CLI 版本，或确认您已经使用最新版本。如果安装过程挂起，请确保允许通过 SSLSSL 安全套接字层——从服务器到浏览器以及反向传输的加密。防止他人窥探您在浏览器和服务器之间发送的内容。（端口 443）和 git（端口 9418）连接到 GitHub，以建立出站连接。

如果 WP-CLI 输出与预期不同，我应该怎么办？

在开始调查错误之前，您应该了解可能改变 WP-CLI 默认行为的因素，以及如何检查它们是否可能是问题的根源。修改此默认行为主要有五个子系统：环境变量、配置文件、WP-CLI 软件包、wp-config.php 文件和 WordPress 扩展（插件、主题、必须使用的插件、drop-in）。

环境变量

工作环境的设置是运行 WP-CLI 的前提。您可以使用 shell 命令 env 检查当前环境设置。

如果您想使用 SSHSSH 安全 Shell——一种用于安全连接远程系统的协议，可作为密码连接的补充或替代。 远程运行 WP-CLI，则远程服务器的路径中必须可以访问 wp 命令。WP-CLI 的行为还可以在运行时通过环境变量进行更改：

  • WP_CLI_CACHE_DIR – 用于存储 WP-CLI 文件缓存的目录。默认为 ~/.wp-cli/cache/。
  • WP_CLI_CONFIG_PATH – 全局 config.yml 文件的路径。默认为 ~/.wp-cli/config.yml。
  • WP_CLI_CUSTOM_SHELL – 允许用户覆盖默认使用的 /bin/bash shell。
  • WP_CLI_DISABLE_AUTO_CHECK_UPDATE – 禁用 WP-CLI 自动检查更新。
  • WP_CLI_DOCKER_NO_TTY – 忽略检测到的 tty 状态，并在通过 ssh 对 Docker 容器运行 WP-CLI 时，从 docker exec 中移除 --tty 标志。
  • WP_CLI_DOCKER_NO_INTERACTIVE – 忽略检测到的 tty 状态，并在通过 ssh 对 Docker 容器运行 WP-CLI 时，从 docker exec 中移除 --interactive 标志。
  • WP_CLI_PACKAGES_DIR – 用于存储通过 WP-CLI 软件包管理安装的软件包的目录。默认为 ~/.wp-cli/packages/。
  • WP_CLI_PHP – 覆盖系统默认值时使用的 PHP 二进制文件路径（仅适用于非 Phar 安装）。
  • WP_CLI_PHP_ARGS – 调用 WP-CLI 时传递给 PHP 二进制文件的参数（仅适用于非 Phar 安装）。
  • WP_CLI_SSH_PRE_CMD – 使用 --ssh=<ssh> 时，在 WP-CLI 调用远程服务器上的 WP-CLI 之前执行的命令。
  • WP_CLI_SSH_BINARY – 使用 --ssh=<ssh> 时，将在远程机器上调用的命令，用于替代 wp。
  • WP_CLI_STRICT_ARGS_MODE – 通过让 WP-CLI 将命令之前的所有参数视为全局参数、命令之后的参数视为本地参数，来避免歧义。
  • WP_CLI_SUPPRESS_GLOBAL_PARAMS – 设置为 true，以跳过在帮助屏幕末尾显示全局参数。这可以为高级用户节省屏幕空间。
  • WP_CLI_FORCE_USER_LOGIN – 设置为 1，强制将提供给 --user 标志的值解释为登录名而不是 ID，以解决类型歧义。
  • WP_CLI_EARLY_REQUIRE – 在引导过程早期加载一个或多个自定义 PHP 文件（以逗号分隔）。
  • WP_CLI_REQUIRE – 在引导过程之后加载一个或多个自定义 PHP 文件（以逗号分隔）。其效果与命令行中的 --require 或 wp-cli.yml 配置文件中的 require 映射相同。
  • WP_CLI_USER_AGENT – 设置某些插件和工具所依赖的 $_SERVER['HTTP_USER_AGENT'] 值。

要按需设置环境变量，可以将环境变量定义放在要运行的 WP-CLI 命令之前（例如 EDITOR=vim wp post edit 1）；要覆盖环境变量，请在 ~/.bashrc 或 ~.zhsrc 中使用 export VARIABLE=value。

WP-CLI 配置文件

配置文件可以让您自定义 WP-CLI 的行为，以适应个人需求或项目需求。如果配置文件不正确，或包含不需要的默认行为修改，WP-CLI 的输出很可能会反映出该错误。

请注意，项目配置文件可以覆盖全局配置文件中的设置。

重命名或删除您的配置文件，然后比较结果，以确定某个配置设置是否可能导致了问题。

WP-CLI 软件包

WP-CLI 软件包是由社区维护的、基于 WP-CLI 构建的项目。它们可以包含 WP-CLI 命令，也可以仅以某种方式扩展 WP-CLI。即使 WP-CLI 工作完全正常，存在错误的软件包也可能导致意外结果。要跳过加载所有已安装的软件包，请使用 wp --skip-packages。

WordPress 配置文件（wp-config.php）

移动或编辑 wp-config.php 超出 WP-CLI 支持的范围可能会导致错误。如果遇到解析错误，请检查 wp-config.php 的文件编码（UTF-8，无 BOM）。

请确保 require_once(ABSPATH . 'wp-settings.php'); 这一行仍保留在 wp-config.php 文件中，并且不要对 wp-config.php 做常量定义之外的修改。如果在 wp-config.php 中调用 WordPress 函数，PHP 将出现致命错误。

如果您想在 wp-config.php 中使用 $_SERVER['HTTP_HOST']，则需要在 WP-CLI 上下文中设置一个默认值：

if ( defined( 'WP_CLI' ) && WP_CLI && ! isset( $_SERVER['HTTP_HOST'] ) ) {
    $_SERVER['HTTP_HOST'] = `example.com';
}

请使用 dirname( __FILE__ ) 或类似内容代替 $_SERVER['document_root']。

WordPress 扩展

WordPress 主题和插件可能会与 WP-CLI 的加载过程冲突或造成干扰，例如重定向用户。它们经常会做出在 WP-CLI 上下文中并不成立的假设，例如使用当前请求的主机名（这是一个在命令行上下文中不存在的概念）。

您可以绕过单个插件和主题（例如 --skip-plugins=akismet），或完全跳过它们（wp --skip-plugins --skip-themes）。

如果 WP-CLI 报告错误，我应该怎么办？

常见问题通常是由 wp-config.php 或 Web 服务器配置的更改导致的。手册的“常见问题”部分列出了最常见的错误消息，并解释了如何处理这些错误。

尝试在全新安装的 WordPress 中，使用默认主题（Twenty …）且不安装任何插件来重现该问题。如果问题仅在自定义环境中重现，那么问题是您环境中的错误，而不是 WP-CLI 的错误。同时，请确保通过在 wp-config.php 中设置常量 define( 'WP_DEBUG', true ); 来启用 WordPress 的调试模式。这可能会揭示现有 WordPress 安装中的问题，而这些问题并非由 WP-CLI 引起。

此外，您还可以使用 WP-CLI 的全局参数 --debug 来显示所有 PHP 错误，并增加 WP-CLI 引导过程的详细程度。

我已经检查了上述所有内容，但问题仍然存在。我可以在哪里报告问题？

如果您认为发现了错误，我们很乐意听取您的反馈，以便修复它。

WP-CLI 的错误报告在 GitHub 上处理。创建新问题之前，请搜索现有问题，查看是否已有解决方案。如果没有针对您的错误的开放或已修复问题，请遵循提交错误报告的指南，以确保问题能够及时得到处理。提供下面所述的摘要、重现步骤、环境详细信息及其他具体信息，将有助于确保您提交的是完整的错误报告。

请向我们提供：
* 以叙述形式概述问题，
* 详细且具体的重现问题步骤列表，
* 您所使用环境的详细信息，
* 描述错误如何影响您的使用（即预期结果与实际结果的对比），包括 * 严重性级别，
* 可能的解决方法，以及
* 相关诊断信息，例如崩溃报告、堆栈跟踪或调试输出。

您可以在提交错误报告的指南中找到问题报告中这些详细信息的完整说明。