WP-CLI 安装指南：Linux、macOS 和 Windows 上正确安装

本文介绍如何在 Debian、Ubuntu、Fedora、RHEL、AlmaLinux、Rocky Linux、macOS 和 Windows（通过 WSL）上逐步安装 WP-CLI。

本文还涵盖了 PHP、MySQL、所需扩展的安装以及完整的预先检查。请按顺序执行每一步，尤其是在新服务器或全新安装的操作系统上。

开始之前

这是 WP-CLI 系列的第 2 部分。如果你还没有阅读第 1 部分，请先阅读。

第 1 部分：什么是 WP-CLI 以及为什么每个 WordPress 专业人士都在使用它

它解释了什么是 WP-CLI，为什么专业人士使用它，以及哪些托管方案支持它。

先决条件清单

在下载 WP-CLI 之前，你的系统需要满足五个条件。如果缺少任何一个，WP-CLI 要么无法安装，要么在你运行第一个命令时立即抛出致命错误。请从头到尾检查此清单。

先决条件 1：类 UNIX 环境

WP-CLI 原生运行在 Linux、macOS 和 FreeBSD 上。在 Windows 上，请使用 WSL（适用于 Linux 的 Windows 子系统）。WP-CLI 不能在原生的 Windows 命令提示符或 PowerShell 中运行。

确认你的 shell 可以工作：

whoami
pwd

这两个命令都应该返回输出且没有错误。如果正常，你的环境就准备好了。

先决条件 2：SSH 访问

WP-CLI 需要终端访问你的服务器。在本地机器上，这已经可用。在远程服务器上，你的托管方案需要启用 SSH enabled。

验证 SSH 访问是否正常：

echo "SSH is working"

如果你看到该行被打印回来，说明你拥有所需的访问权限。如果你不确定你的托管方案是否包含 SSH，请参阅本系列第 1 部分中的托管要求章节。

先决条件 3：PHP 7.2.24 或更高版本及所需扩展

如果这是新服务器或全新安装的操作系统，PHP 可能根本不存在。首先运行此检查：

php --version

如果你看到 "command not found"，请先安装 PHP。

你需要 PHP 7.2.24 或更高版本（这是官方文档明确要求的最低版本）。如果你的版本更旧，请在继续之前更新 PHP。

在 Ubuntu / Debian 中安装带有所需扩展的 PHP：

sudo apt update
sudo apt install php php-cli php-mysql php-curl php-xml php-mbstring php-zip php-gd php-intl php-bcmath

Fedora / RHEL / CentOS / AlmaLinux / Rocky Linux：

sudo dnf install php php-cli php-mysqlnd php-curl php-xml php-mbstring php-zip php-gd php-intl php-bcmath

openSUSE：

sudo zypper install php8 php8-cli php8-mysql php8-curl php8-xml php8-mbstring php8-zip php8-gd php8-intl php8-bcmath

macOS（通过 Homebrew）：

brew install php

注意： macOS 上默认包含了大多数必需的扩展。

安装后，确认 PHP 已就绪：

php --version
php -m | grep -E 'mysqli|curl|xml|mbstring|zip|gd|intl'

在进入下一步之前，两个检查都应该返回输出。

当查询 PHP 扩展时，你应该看到每个扩展名称被打印回来。如果输出中缺少任何扩展，请安装该扩展的特定版本软件包并重新运行检查。

以下是每个扩展的作用，以便你确切知道为什么需要它：

先决条件 4：MySQL 或 MariaDB 正在运行且可访问

WordPress 将所有内容（内容、设置、用户和选项）存储在数据库中。如果没有正在运行的数据库服务器，wp config create 和 wp core install 都会立即因连接错误而失败。

WordPress 推荐 MySQL 8.0+ 或 MariaDB 10.6+ 作为安全、现代的基线，以获得性能和安全性。对于任何新安装，请使用 MySQL 8.4 LTS 或 MariaDB 10.11 LTS。两者都有很长的支持窗口。

检查数据库服务器是否已安装

mysql --version
# or
mariadb --version

如果你看到两者的 "command not found"，请立即安装一个。

安装 MySQL

Debian / Ubuntu / Linux Mint：

sudo apt update
sudo apt install mysql-server

RHEL / CentOS / AlmaLinux / Rocky Linux：

sudo dnf install mysql-server

安装 MariaDB（推荐作为替代品）

Debian / Ubuntu / Linux Mint：

sudo apt update
sudo apt install mariadb-server

Fedora / RHEL / CentOS / AlmaLinux / Rocky Linux：

sudo dnf install mariadb-server

openSUSE：

sudo zypper install mariadb

macOS（通过 Homebrew）：

brew install mariadb

启动并启用服务

# For MySQL
sudo systemctl start mysql
sudo systemctl enable mysql
# For MariaDB
sudo systemctl start mariadb
sudo systemctl enable mariadb

enable 标志使服务在服务器每次重启时自动启动。没有它，你每次都必须手动启动数据库。

运行安全安装向导

推荐用于任何非 Docker、非本地环境：

# For MySQL
sudo mysql_secure_installation
# For MariaDB
sudo mariadb-secure-installation

这会删除默认的测试数据库，禁用远程 root 登录，并设置一个强 root 密码。大约需要两分钟，并能显著提高数据库安全性。

创建 WordPress 数据库和用户

sudo mysql -u root -p

然后在 MySQL/MariaDB 提示符下，运行以下 SQL 命令：

CREATE DATABASE wordpress CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wpuser'@'localhost' IDENTIFIED BY 'StrongPassword123';
GRANT ALL PRIVILEGES ON wordpress.* TO 'wpuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

将以下内容替换为你自己的值：

wordpress - 你首选的数据库名称（例如 mysite_db）。
wpuser - 你首选的数据库用户名。
StrongPassword123 - 一个强且唯一的密码。切勿在真实服务器上使用简单密码。

CHARACTER SET utf8mb4 设置确保 WordPress 从一开始就能正确处理国际字符、表情符号和特殊符号。FLUSH PRIVILEGES 行告诉数据库服务器立即重新加载其权限表。

验证数据库连接

在继续之前，确认新用户确实可以连接：

mysql -u wpuser -p wordpress

如果这能打开 MySQL 提示符且没有错误，你的数据库就准备好了。输入 exit 退出。

为什么有时使用 127.0.0.1 而不是 localhost： 当你传递 --dbhost=localhost 时，PHP 通过 Unix 套接字文件连接。如果该套接字路径在你的系统上 PHP 和 MySQL 之间不同，你会得到错误 2002 "No such file or directory." 使用 --dbhost=127.0.0.1 强制 PHP 改用 TCP 连接，从而完全绕过套接字。如果 localhost 抛出该错误，请切换到 127.0.0.1。

先决条件 5：WordPress 4.9 或更高版本

WP-CLI 需要 WordPress 4.9 或更高版本。比最新 WordPress 版本更旧的版本可能功能会退化。对于全新安装，这不是问题，因为使用 wp core download 下载 WordPress 核心总是拉取最新的稳定版本。但是，如果你针对现有的旧站点运行 WP-CLI，请先检查你的 WordPress 版本：

wp core version

如果版本低于 4.9，请在依赖 WP-CLI 之前更新 WordPress：

wp core update

全面预先检查

在下载 WP-CLI 之前，运行所有四个检查。在继续之前，每一行都必须返回干净的输出且没有错误。

# 1. Confirm PHP version is 7.2.24 or higher
php --version
# 2. Confirm all required extensions are loaded
php -m | grep -E 'mysqli|curl|xml|mbstring|zip|gd|intl|bcmath'
# 3. Confirm MySQL or MariaDB is running
sudo systemctl status mysql    # or: sudo systemctl status mariadb
# 4. Confirm you can log into the database with the WordPress user
mysql -u wpuser -p wordpress -e "SELECT 'Connection OK';"

所有四个检查必须顺利通过。一旦通过，下载 WP-CLI。

步骤 1：验证 SSH 访问

在下载 WP-CLI 之前，做一个快速的最终检查，确认你的 shell 会话是活动的，并且你在服务器上的正确位置：

whoami   # shows which user you are running as
pwd      # shows which directory you are currently in

这两个命令都应该返回输出且没有错误。如果你在远程服务器上，请确保在继续之前已通过 SSH 连接。如果你在本地工作，例如在 Docker 容器或本地 Linux 环境中，你已经拥有访问权限，可以直接进入步骤 2。

步骤 2：下载 WP-CLI

使用以下命令下载最新的稳定版 WP-CLI：

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

或者，如果你的系统上没有 curl，可以使用 wget：

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

对于那些不了解的人，PHAR 文件是一个自包含的 PHP 应用程序。

验证 PHAR 签名

此步骤推荐用于生产服务器和安全敏感的环境。它确认下载的文件未被篡改。

下载签名文件：

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

然后根据 WP-CLI 公钥验证它：

gpg --keyserver keyserver.ubuntu.com --recv-keys 63AF7AA15067C05616FDDD88A3A2E8F226F0BC06
gpg --verify wp-cli.phar.asc wp-cli.phar

一个有效的文件返回 Good signature from "WP-CLI (Signing Key)"。如果验证失败，请删除 PHAR 文件并重新下载。不要安装签名验证失败的文件。

步骤 3：验证下载

在系统范围内安装之前，测试下载的文件是否正确运行：

php wp-cli.phar --info

这应该显示 WP-CLI 版本信息和你的系统配置、PHP 二进制路径、PHP 版本和操作系统详细信息。如果你看到该输出，则文件有效并可以安装。

步骤 4：使其全局可访问

授予文件可执行权限，然后将其移动到你的系统路径，以便你可以从任何目录运行 wp：

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

步骤 5：确认安装

验证 wp 命令可以从系统上的任何位置工作：

wp --info

如果你看到版本和系统信息，则 WP-CLI 已完全安装并可以使用。这是你应该期望的输出：

OS:	Linux 7.0.0-15-generic #15-Ubuntu SMP PREEMPT_DYNAMIC Wed Apr 22 16:06:43 UTC 2026 x86_64
Shell:	/bin/bash
PHP binary:	/usr/bin/php8.5
PHP version:	8.5.4
php.ini used:	/etc/php/8.5/cli/php.ini
MySQL binary:
MySQL version:
SQL modes:
WP-CLI root dir:	phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:	phar://wp-cli.phar/vendor
WP_CLI phar path:	phar:///usr/local/bin/wp
WP-CLI packages dir:
WP-CLI cache dir:	/home/senthilkumar/.wp-cli/cache
WP-CLI global config:
WP-CLI project config:
WP-CLI version:	2.12.0

有关官方安装文档，请访问：https://wp-cli.org/#installing。

替代安装方法

上述 PHAR 方法适用于每个系统。但是，有两种替代方法可能更适合你的工作流程。

Ubuntu PPA（apt 安装）

如果你管理 Ubuntu 或 Debian 服务器，并且更喜欢通过 apt 安装工具，一个社区-maintained 的 PPA 提供了 WP-CLI 的打包版本：

sudo add-apt-repository ppa:tiagohillebrandt/wp-cli
sudo apt update
sudo apt install wp-cli

该 PPA 由社区志愿者维护，可能比最新的 WP-CLI 版本稍晚。对于最新版本，请使用上面的 PHAR 方法。安装后，使用 wp cli version 验证你拥有的版本。

Composer 全局安装

如果你已经在 PHP 开发工作流程中使用 Composer，你可以将 WP-CLI 安装为全局 Composer 软件包：

composer global require wp-cli/wp-cli-bundle

确保你的 Composer 全局 bin 目录在你的 $PATH 中。在大多数系统上，它是 ~/.composer/vendor/bin 或 ~/.config/composer/vendor/bin：

export PATH="$HOME/.composer/vendor/bin:$PATH"

将该行添加到你的 ~/.bash_profile 以使其永久生效。然后确认 WP-CLI 工作：

wp --info

如果你希望 WP-CLI 在项目中固定到特定版本，或者你的团队使用 Composer 进行跨工具的依赖管理，那么 Composer 方法是理想的。

在共享主机上安装

一些共享主机预装了 WP-CLI。请查阅你的主机文档，或者在通过 SSH 登录后直接运行 wp --info。如果它返回输出，则 WP-CLI 已经存在。

如果它没有预装，但你的方案包含 SSH 访问，你可以直接运行 PHAR 文件，而无需将其移动到全局路径：

php wp-cli.phar --info

为了使其更容易输入，在你的 ~/.bash_profile 中添加一个别名：

alias wp='php ~/wp-cli.phar'

然后重新加载配置文件：

source ~/.bash_profile

之后，wp --info 就像全局安装一样工作。

启用 Tab 补全

WP-CLI 支持 Bash、Zsh 和 Fish 中的 Tab 补全。你可以从此链接下载补全脚本：https://github.com/wp-cli/wp-cli/raw/main/utils/wp-completion.bash。

对于 Bash，下载补全脚本并从 ~/.bash_profile 中引用它：

source /FULL/PATH/TO/wp-completion.bash

然后重新加载你的配置文件：

source ~/.bash_profile

对于 带有 Oh My Zsh 的 Zsh，将 wp-cli 添加到你的 ~/.zshrc 中的 plugins 行：

plugins=(wp-cli git ...)

对于 Fish shell，下载 wp.fish 并将其放置在 ~/.config/fish/completions/wp.fish 中。当你输入 wp 并按 Tab 键时，Fish 会自动引用它。

常见问题解答

问：WP-CLI 的最低 PHP 版本是多少？

答：WP-CLI 需要 PHP 7.2.24 或更高版本。2026 的推荐版本是 PHP 8.4。它更快，得到积极支持，并且是大多数主机当前使用的版本。使用 php --version 确认你的版本。

问：我安装了 PHP，但 WP-CLI 仍然抛出关于 mysqli_init 的致命错误。出了什么问题？

答：PHP 已安装，但缺少 php-mysql 扩展。使用 sudo apt install php-mysql（Ubuntu/Debian）或 sudo dnf install php-mysqlnd（RHEL/Fedora）安装它。然后使用 php -m | grep mysqli 确认它已加载。

问：运行 wp config create 时出现错误 2002 "No such file or directory"。如何修复？

答：将 --dbhost=localhost 替换为 --dbhost=127.0.0.1。这会强制 PHP 使用 TCP 连接而不是 Unix 套接字，从而修复某些系统上 PHP 和 MySQL 套接字路径不匹配的问题。

问：我可以在没有 sudo 权限的情况下安装 WP-CLI 吗？

答：可以。跳过 sudo mv 步骤，而是直接使用 php wp-cli.phar <command> 运行 PHAR 文件，或者将其保存到用户 PATH 中的目录，如 ~/bin/wp，并将 ~/bin 添加到你的 $PATH 中。

问：当我更新 PHP 时，是否需要重新安装 WP-CLI？

答：不需要。WP-CLI 是一个自包含的 PHAR 文件，在 PHP 更新后不需要重新安装。但是，请定期运行 wp cli update 以保持 WP-CLI 本身是最新的。

问：安装 WP-CLI 后如何更新它？

答：从任何位置运行此命令：

wp cli update

首先检查可用的更新而不应用它们：

wp cli check-update

下一步

WP-CLI 已安装并验证。你现在可以开始运行命令了。继续阅读 WP-CLI 系列的第 3 部分，学习基本的 WP-CLI 命令：

第 3 部分：WP-CLI 命令 - 完整参考指南

该指南详细介绍了每个命令类别——插件、主题、用户、数据库、多站点、自动化脚本、CI/CD 集成、自定义命令和安全最佳实践。它还包括一个完整的速查表，你可以收藏并随时查阅。

本系列还包括：

WP-CLI 安装指南：在 Linux、macOS 和 Windows 上正确安装