phpbrew 使用教程 — 在 Linux/macOS 上管理多个 PHP 版本

什么是 phpbrew

phpbrew 是一个 PHP 版本管理工具，允许你在同一台机器上安装、编译、切换多个 PHP 版本。它从源码编译 PHP，因此你可以自由定制扩展和编译参数，非常适合需要测试不同 PHP 版本兼容性的开发者。

与之类似的还有 phpenv（rbenv 风格）和 phpenv，但 phpbrew 功能最全面，支持的 PHP 版本最广。

安装 phpbrew

依赖要求

  • Linux 或 macOS
  • PHP 7.2+（作为 phpbrew 自身运行时）
  • curl、git、gcc/make 等编译工具
  • autoconf、automake、libtool 等库（编译 PHP 时需要）

以 Ubuntu/Debian 为例，提前安装编译依赖：

1
2
3
4
5
6
7
sudo apt update
sudo apt install -y \
  php-cli php-json \
  autoconf automake libtool re2c bison \
  libxml2-dev libsqlite3-dev libcurl4-openssl-dev \
  libonig-dev libicu-dev libzip-dev \
  libgd-dev libxpm-dev libfreetype6-dev

方式一：官方安装脚本（推荐）

1
2
3
curl -L -O https://github.com/phpbrew/phpbrew/releases/latest/download/phpbrew.phar
chmod +x phpbrew.phar
sudo mv phpbrew.phar /usr/local/bin/phpbrew

方式二：直接克隆仓库

1
2
3
git clone https://github.com/phpbrew/phpbrew.git
cd phpbrew
phpbrew.phar install

安装完成后，需要在 shell 配置文件中初始化。编辑 ~/.bashrc 或 ~/.zshrc，添加：

1
2
export PHPBREW_ROOT="$HOME/.phpbrew"
source "$PHPBREW_ROOT/bashrc"

然后重新加载：

1
source ~/.bashrc   # 或 source ~/.zshrc

运行 phpbrew version 验证安装成功。

初始化

首次使用需要初始化：

1
phpbrew init

这会在 $PHPBREW_ROOT（默认为 ~/.phpbrew）下创建必要目录，并在 ~/.phpbrew/init 生成环境变量配置。

查看可用 PHP 版本

1
2
3
4
phpbrew known          # 列出当前可用版本
phpbrew known --more   # 显示更多旧版本
phpbrew known --old    # 显示 PHP 5.3 之前的远古版本
phpbrew known -u       # 更新版本列表

输出类似：

1
2
3
4
5
6
7
Known PHP versions:
  php-8.3.0
  php-8.2.0
  php-8.1.0
  php-8.0.0
  php-7.4.0
  ...

安装 PHP

基本安装

1
phpbrew install php-8.2.0

这会从 PHP 官网下载源码，configure、make、make install，全程自动化。

指定编译变体（variants）

phpbrew 使用”变体”（variant）机制来组合常用扩展。常用变体：

变体 说明
default 默认常用扩展集（bcmath、curl、json、opcache、pdo、readline…）
mb mbstring + mbregex，多字节字符串支持
dbs sqlite + mysql + pgsql，数据库支持
fpm 编译 PHP-FPM（用于配合 Nginx/Apache）
phpdbg 编译 phpdbg 调试器
opcache Zend OPcache
all 几乎所有扩展（测试兼容性用，编译慢）

安装带常用扩展的 PHP：

1
phpbrew install php-8.2.0 +default +mb +fpm +opcache

安装极简版（仅 CLI）：

1
phpbrew install php-8.2.0 +minimal

从已有版本继承变体

1
phpbrew install php-8.1.0 --like=php-8.2.0

这样 8.1.0 会自动继承 8.2.0 安装时使用的变体组合。

编译加速

多核机器加 -j 参数并行编译：

1
phpbrew install php-8.2.0 +default -j$(nproc)

安装后运行测试

1
phpbrew install php-8.2.0 +default --test

常见编译问题处理

缺少库：安装时缺什么库，系统会报错。根据错误信息安装对应 dev 包即可。

Visual C++ 运行库（Windows 下特有）：Linux/macOS 无此问题。

并发冲突：某些扩展组合会冲突，如 mcrypt + sodium。通常去掉冲突扩展即可。

已安装版本列表

1
phpbrew list

如果还没安装任何版本，会提示：Please install at least one PHP with your preferred version.

切换 PHP 版本

临时切换（仅当前 shell 生效）

1
phpbrew use php-8.2.0

退出当前 shell 后失效，恢复系统默认或 phpbrew 默认版本。

永久切换（全局默认）

1
phpbrew switch php-8.2.0

会将版本写入 ~/.phpbrew/init，每次新开 shell 自动加载。

关闭 phpbrew，切回系统 PHP

1
phpbrew off

查看当前使用中的版本

1
2
3
phpbrew use
# 或
phpbrew current

FPM 管理

phpbrew 内置了 php-fpm 的启停管理（前提是编译时加了 +fpm 变体）：

1
2
3
4
5
6
7
8
phpbrew fpm start          # 启动
phpbrew fpm stop           # 停止
phpbrew fpm restart        # 重启
phpbrew fpm test           # 测试配置
phpbrew fpm config         # 编辑 php-fpm.conf
phpbrew fpm info           # 查看 php-fpm 配置信息
phpbrew fpm module         # 列出已编译的 fpm 模块
phpbrew fpm current        # 查看当前 fpm 进程状态

编辑 php.ini

1
2
3
phpbrew config           # 用 $EDITOR 打开当前版本的 php.ini
phpbrew config --sapi cli # 仅编辑 CLI 的 php.ini
phpbrew config --sapi fpm # 仅编辑 FPM 的 php.ini

清理构建产物

安装后删除源码目录节省空间（保留已编译的 php 目录）：

1
2
3
4
phpbrew purge php-8.2.0
# 或
phpbrew purge php-8.2.0 --build
# --build 仅删源码，保留已安装的二进制

删除已安装的 PHP 版本

1
phpbrew purge php-8.1.0 php-8.0.0   # 同时删除多个版本

注意：正在使用中的版本无法被 purge，需要先 phpbrew switch 到其他版本。

批量操作：each

对所有已安装版本执行同一命令：

1
2
phpbrew each php -v           # 所有版本的 php -v
phpbrew each "php -m | grep opcache"   # 检查各版本是否装了 opcache

.phpbrewrc：项目级 PHP 版本锁定

在项目根目录放一个 .phpbrewrc 文件，内容如：

1
php-8.2.0 +default +mb

进入该目录时，phpbrew 会自动切换到指定版本（需要 $PHPBREW_RC_ENABLE=1）。

常见使用场景

场景一：测试项目在不同 PHP 版本的兼容性

1
2
3
4
5
6
7
8
phpbrew install php-7.4.0 +default +mb +fpm
phpbrew install php-8.0.0 +default +mb +fpm
phpbrew install php-8.1.0 +default +mb +fpm
phpbrew install php-8.2.0 +default +mb +fpm

# 快速切换测试
phpbrew switch php-7.4.0 && php composer install && php vendor/bin/phpunit
phpbrew switch php-8.2.0 && php composer install && php vendor/bin/phpunit

场景二：本地多项目，不同版本需求

项目 A 需要 PHP 7.4，项目 B 需要 PHP 8.2，通过 .phpbrewrc 在各自目录下自动切换。

场景三：开发时用 phpdbg 调试

1
2
3
phpbrew install php-8.1.0 +default +phpdbg
phpbrew switch php-8.1.0
phpdbg -qrr /path/to/script.php

完整工作流示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 1. 安装两个版本
phpbrew install php-8.2.0 +default +mb +fpm +opcache
phpbrew install php-8.1.0 +default +mb

# 2. 切换到 8.2 作为默认
phpbrew switch php-8.2.0

# 3. 确认当前版本
php -v

# 4. 编辑 php.ini 打开 OPcache
phpbrew config
# 在 php.ini 中设置 opcache.enable=1

# 5. 需要测试 8.1 时
phpbrew switch php-8.1.0

# 6. 不需要时清理
phpbrew purge php-8.1.0

常见问题

Q: 编译时提示 “mbregex” 冲突？
A: 去掉 mbregex 变体，单独使用 mbstring 即可。

Q: macOS 上编译失败？
A: 确保安装 Command Line Tools（xcode-select --install）和 Homebrew 依赖库。

Q: 如何让 phpbrew 使用代理？
A: phpbrew install php-8.2.0 --http-proxy=http://127.0.0.1:7890

Q: phpbrew 自身需要 PHP 多少版本？
A: phpbrew 需要 PHP 7.2+ 作为运行时解释器。

卸载 phpbrew

如果不再需要 phpbrew，清理步骤：

1
2
3
4
5
6
7
8
9
10
# 1. 移除 phpbrew 主程序
sudo rm /usr/local/bin/phpbrew

# 2. 删除配置和已安装的 PHP 版本
rm -rf ~/.phpbrew

# 3. 从 shell 配置中移除初始化代码
# 从 ~/.bashrc 或 ~/.zshrc 中删除以下内容：
#   export PHPBREW_ROOT="$HOME/.phpbrew"
#   source "$PHPBREW_ROOT/bashrc"

phpbrew 是本地 PHP 环境管理的利器，尤其适合需要同时维护多个项目、对接不同 PHP 版本依赖的场景。建议安装完 PHP 后顺手 phpbrew switch 设好默认版本，配合 .phpbrewrc 实现项目级自动切换，可以大幅减少版本相关的扯皮时间。

#PHP #开发工具 #环境管理
phpbrew 使用教程 — 在 Linux/macOS 上管理多个 PHP 版本
https://kingjem.github.io/2026/04/11/phpbrew使用教程/
作者
Ruhai
发布于
2026年4月11日
许可协议