用 phpbrew 管理 php 环境:从安装到多版本切换

在 macOS 开发环境里,PHP 的麻烦往往不只是"装一个能跑的版本",而是"怎么同时维护多个版本,还能随时切换"。有的项目还停在 PHP 8.2,有的已经切到 8.4,如果只靠手动改 PATH,环境很容易混乱。phpbrew 的价值,就是把 PHP 多版本安装和切换这件事收拢到一套可重复的流程里。

需要先明确一点:phpbrew 除了负责版本切换,还会从源码编译并安装指定 PHP 版本。这意味着它不仅要初始化 shell,还要提前准备好编译依赖。

给 AI Agent 的提示词:

使用 Homebrew 安装 phpbrew,执行 phpbrew init 初始化环境,在 shell 中加载 ~/.phpbrew/bashrc,配置好编译依赖和相关环境变量后,通过 phpbrew install 编译安装多个 PHP 版本,再使用 phpbrew use、phpbrew switch 和 phpbrew off 在不同版本之间切换。

一、安装 phpbrew

在 macOS 上,可以直接通过 Homebrew 安装:

bash 复制代码
brew install phpbrew

安装完成后先确认版本:

bash 复制代码
phpbrew --version

如果还没有配置 Homebrew,本机常见的 Homebrew 前缀是:

bash 复制代码
/opt/homebrew

这通常也是 Apple Silicon Mac 上大多数依赖库的安装位置。

二、初始化 phpbrew

安装完 phpbrew 后,先执行初始化:

bash 复制代码
phpbrew init

这一步会创建:

bash 复制代码
~/.phpbrew/
~/.phpbrew/bashrc

随后需要把 phpbrew 的初始化脚本加入 shell 配置。以 zsh 为例,可以把下面这段加入 ~/.zshrc:

bash 复制代码
#  PHPBrew / PHP
export PATH="/opt/homebrew/opt/php@8.4/bin:/opt/homebrew/opt/php@8.4/sbin:$PATH"
export PHPBREW_SYSTEM_PHP="$HOME/.local/bin/phpbrew-php"
[[ -r "$HOME/.phpbrew/bashrc" ]] && source "$HOME/.phpbrew/bashrc"

然后重新加载 shell:

bash 复制代码
source ~/.zshrc

建议立刻验证加载结果:

bash 复制代码
which php
php -v
type phpbrew
phpbrew --version

如果输出里看到:

  • php 指向 /opt/homebrew/opt/php@8.4/bin/php
  • phpbrew is a shell function from ~/.phpbrew/bashrc

说明初始化已经生效。

三、处理 PHP 8.4 下的 deprecation 噪声

这台机器上的一个实际问题是:Homebrew 安装的 phpbrew 在 PHP 8.4 环境下运行时,会打印一批 Deprecated: 提示。它不一定会让功能失效,但会让输出非常脏,尤其是在安装和切换版本时更明显。

比较稳妥的处理方式,是为 phpbrew 单独准备一个包装器,调用系统 PHP 时屏蔽这些 deprecation 噪声。可以创建:

bash 复制代码
mkdir -p ~/.local/bin
cat > ~/.local/bin/phpbrew-php <<'EOF'
# !/bin/sh
exec /opt/homebrew/opt/php@8.4/bin/php -d error_reporting='E_ALL & ~E_DEPRECATED & ~E_STRICT' "$@"
EOF
chmod +x ~/.local/bin/phpbrew-php

然后在 ~/.zshrc 里设置:

bash 复制代码
export PHPBREW_SYSTEM_PHP="$HOME/.local/bin/phpbrew-php"

这样做的目的不是替换你日常使用的 php,而是让 phpbrew 自己在执行时更安静、更稳定。

四、安装编译依赖

由于 phpbrew 安装 PHP 的方式是源码编译,所以在真正执行 phpbrew install 之前,需要先准备编译依赖。

建议先安装这些常用依赖:

bash 复制代码
brew install bison libiconv libxml2 re2c bzip2 zip

这台机器上原本已经具备的常见依赖还包括:

  • openssl@3
  • curl
  • sqlite
  • readline
  • libsodium
  • oniguruma
  • pkgconf

如果这些基础库缺失,后续编译 PHP 时经常会在 configure 或 make 阶段报错。

五、为 phpbrew 编译准备环境变量

在 Apple Silicon 的 Homebrew 环境里,很多依赖不在系统默认搜索路径里,所以在安装 PHP 之前,最好先把相关头文件和 pkg-config 路径明确暴露出来:

bash 复制代码
export PATH="/opt/homebrew/opt/bison/bin:/opt/homebrew/opt/libxml2/bin:/opt/homebrew/opt/bzip2/bin:/opt/homebrew/opt/zip/bin:$PATH"
export PKG_CONFIG_PATH="/opt/homebrew/opt/libxml2/lib/pkgconfig:/opt/homebrew/opt/openssl@3/lib/pkgconfig:/opt/homebrew/opt/sqlite/lib/pkgconfig:/opt/homebrew/opt/readline/lib/pkgconfig:/opt/homebrew/opt/libsodium/lib/pkgconfig:/opt/homebrew/opt/oniguruma/lib/pkgconfig:/opt/homebrew/opt/curl/lib/pkgconfig:/opt/homebrew/opt/libiconv/lib/pkgconfig:$PKG_CONFIG_PATH"
export CPPFLAGS="-I/opt/homebrew/opt/libiconv/include -I/opt/homebrew/opt/libxml2/include -I/opt/homebrew/opt/bzip2/include $CPPFLAGS"
export LDFLAGS="-L/opt/homebrew/opt/libiconv/lib -L/opt/homebrew/opt/libxml2/lib -L/opt/homebrew/opt/bzip2/lib $LDFLAGS"

如果不先做这一步,phpbrew 在编译某些版本时,往往会出现"找不到头文件"或"扩展功能被静默禁用"的情况。

六、使用 phpbrew 安装 PHP 版本

真正开始安装前,可以先看 phpbrew 当前认识哪些 PHP 版本:

bash 复制代码
phpbrew list-known | head -n 12

比如安装 PHP 8.4.20:

bash 复制代码
phpbrew install --stdout --jobs=4 8.4.20 +default

安装 PHP 8.2.30:

bash 复制代码
phpbrew install --stdout --jobs=4 8.2.30 +default

如果还需要 FPM,可以显式加上:

bash 复制代码
phpbrew install --stdout --jobs=4 8.2.30 +default +fpm

这里有一个本机实测过的细节:--jobs=4 可以正常工作,但不建议写成 -j4。在这台机器上,-j4 被 phpbrew 透传后,会触发 make 报错:

text 复制代码
the '-j' option requires a positive integral argument

所以更稳妥的写法是始终使用 --jobs=4 这种长参数形式。

七、查看和切换已安装的 PHP 版本

安装完成后,可以先看当前已注册的版本:

bash 复制代码
phpbrew list

这台机器当前看到的是:

text 复制代码
* (system)
  php-8.4.20
  php-8.2.30

这里的 system 表示当前 shell 还在使用 Homebrew 提供的系统 PHP,而 php-8.4.20、php-8.2.30 则是已经由 phpbrew 编译并安装好的版本。

只在当前终端会话里临时切换:

bash 复制代码
phpbrew use php-8.4.20

或者:

bash 复制代码
phpbrew use php-8.2.30

切换完成后验证:

bash 复制代码
which php
php -v

本机已验证:

  • phpbrew use php-8.4.20 后,php 指向 ~/.phpbrew/php/php-8.4.20/bin/php
  • phpbrew use php-8.2.30 后,php 指向 ~/.phpbrew/php/php-8.2.30/bin/php

如果想回到系统 PHP:

bash 复制代码
phpbrew off

八、持久切换默认 PHP

如果希望后续新开的 shell 也默认使用某个 phpbrew 安装的版本,可以执行:

bash 复制代码
phpbrew switch php-8.4.20

或者:

bash 复制代码
phpbrew switch php-8.2.30

取消持久切换、恢复到系统 PHP:

bash 复制代码
phpbrew switch-off

这和 phpbrew use 的区别在于:

  • phpbrew use 只影响当前 shell
  • phpbrew switch 会影响后续新开的 shell

九、验证当前生效的 PHP 版本

切换完成后,建议固定用下面几条命令验证:

bash 复制代码
which php
php -v
type phpbrew
phpbrew list

如果要直接确认某个 phpbrew 安装版本是否真的能执行,也可以单独运行:

bash 复制代码
~/.phpbrew/php/php-8.4.20/bin/php -v
~/.phpbrew/php/php-8.2.30/bin/php -v

这类检查比只看 phpbrew list 更可靠,因为它能直接确认目标二进制是否真的可运行。

十、常用命令总结

日常最常用的命令基本包括:

bash 复制代码
phpbrew --version
phpbrew init
phpbrew list-known
phpbrew install --stdout --jobs=4 8.4.20 +default
phpbrew list
phpbrew use php-8.4.20
phpbrew switch php-8.4.20
phpbrew off
phpbrew switch-off

这些命令已经覆盖了安装、初始化、编译、切换和恢复系统版本的主要场景。

十一、推荐的实践方式

比较稳妥的用法通常是:

  • 保留 Homebrew 自带 PHP 作为 system 基线环境
  • 用 phpbrew 安装项目实际需要的版本,比如 php-8.2.x 和 php-8.4.x
  • 临时测试时使用 phpbrew use
  • 长期主力版本使用 phpbrew switch
  • 编译前先固定好依赖路径和 PKG_CONFIG_PATH

这样做的好处是,系统 PHP 和项目 PHP 的边界清楚,多个版本可以并行存在,切换成本也足够低。

十二、常见问题排查

如果执行 phpbrew 时满屏都是 Deprecated: 提示,通常不是 PHP 版本坏了,而是 phpbrew 本身在 PHP 8.4 下的兼容性噪声。这时优先检查 PHPBREW_SYSTEM_PHP 是否已经指向你设置的包装器。

如果 phpbrew install 在 configure 阶段失败,首先检查 Homebrew 依赖是否装齐,其次检查下面这些变量是否已经设置:

bash 复制代码
echo $PATH
echo $PKG_CONFIG_PATH
echo $CPPFLAGS
echo $LDFLAGS

如果编译参数里用了 -j4 之后出现并行构建报错,优先改回:

bash 复制代码
--jobs=4

如果切换后 which php 仍然指向系统 PHP,通常说明当前 shell 没有正确加载:

bash 复制代码
~/.phpbrew/bashrc

这时应重新检查 ~/.zshrc 中的 source 配置是否生效。

结语

phpbrew 的价值不只是"再装一个 PHP",而是把 PHP 的多版本编译、安装和切换变成一套可预期的流程。对于需要同时维护新旧项目的开发环境,这比手动切 PATH 稳定得多。比较实用的思路通常是:保留系统 PHP 作为底座,用 phpbrew 编译项目需要的版本,再通过 use 或 switch 做场景化切换。

参考资料

相关推荐
码事漫谈28 分钟前
以后人人都可以成为导演
后端
Resean022335 分钟前
Spring 源码分析(二)配置类的解析与扫描
java·后端·spring
一只爱撸猫的程序猿35 分钟前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源
北城笑笑2 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
ServBay3 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho3 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
张一凡934 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
00后程序员4 小时前
iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛
后端·ios
程序员cxuan4 小时前
推荐 10 个 WorkBuddy 中的邪修用法
人工智能·后端·程序员
Bacon5 小时前
给项目做一次"全身 CT":Agent Skills 生态里的代码体检全链路
前端·人工智能·后端