17370845950

Homebrew 安装 PHP 后需三步生效：①将 /opt/homebrew/bin（Apple Silicon）或 /usr/local/bin（Intel）加至 $PATH 开头并 source ~/.zshrc；②单独安装扩展如 brew install php-redis、brew install gd，并在 php.ini 中用 extension=gd.so 等启用；③多版本共存时用 brew unlink && brew link php@8.3 切换，并确保 Web 服务器配置指向 Homebrew 的 libphp.so。

Mac 上用 Homebrew 装 PHP，不是装完就能用，关键在路径、版本共存、扩展启用这三步没走对，php -v 显示旧版、php -m 看不到 pdo_mysql、Web 里报 Call to undefined function mysqli_connect()——这些都不是 PHP 没装好，是环境没切过去。

确认 Homebrew 已就绪并替换默认 PHP

macOS 自带 PHP（已废弃），必须让终端优先调用 Homebrew 安装的版本。先检查是否已安装：

brew install php

装完后执行：

which php

如果输出仍是 /usr/bin/php，说明 shell 还在用系统版。需要把 Homebrew 的 bin 目录加到 $PATH 开头：

• 编辑 ~/.zshrc（macOS Catalina 及以后默认用 zsh）
• 追加一行：export PATH="/opt/homebrew/bin:$PATH"（Apple Silicon）或 export PATH="/usr/local/bin:$PATH"（Intel）
• 运行 source ~/.zshrc，再执行 which php，应返回 /opt/homebrew/bin/php

安装常用扩展（如 pdo_mysql、opcache、gd）

Homebrew 的 php 包默认不带所有扩展，需单独安装对应 formula。注意：扩展名 ≠ PHP 中的模块名，例如 php-mysql 对应的是 mysqli 和 pdo_mysql 模块，但实际启用靠配置文件。

• 装 MySQL 支持：brew install mysql（服务端） + brew install php@8.3（若未指定版本，当前默认可能已是 8.3）
• 装 GD 图形库：brew install gd，它会自动为当前 PHP 版本编译 gd.so
• 装 Redis 扩展：brew install php-redis（注意不是 redis 或 phpredis）
• 装 OPcache（已内置，只需启用）：确认 php.ini 中有 zend_extension=opcache

扩展装完不会自动启用，得手动改 php.ini。用 php --ini 查位置，通常在 /opt/homebrew/etc/php/8.3/php.ini。

验证扩展是否生效 & 常见失效原因

改完 php.ini 后必须重启 CLI 或 Web 服务才能生效。常见错误：

• extension=gd.so 写成 extension=gd（少 .so）
• 扩展路径不对：Homebrew 编译的 so 文件在 /opt/homebrew/lib/php/pecl/20250831/ 这类路径下，不能硬写绝对路径，直接写文件名即可
• PHP 版本错配：用 php@8.2 却装了 php@8.3 的扩展，so 文件 ABI 不兼容，php -m 会静默跳过
• Apache / Nginx 用的是另一套 PHP：CLI 能跑，浏览器 500，说明 Web 服务器没连到 Homebrew 的 PHP，要检查 LoadModule php_module 和 AddHandler 配置指向的 libphp.so 是否来自 /opt/homebrew/

快速验证命令：

php -m | grep -E "(pdo|mysql|gd|redis)"

看到对应模块名即表示已加载。

切换 PHP 版本（多版本共存时）

Homebrew 允许同时装多个 PHP 版本（如 php@8.1、php@8.3），但只能有一个被 brew link 激活。切换步骤：

• 先 unlink 当前：brew unlink php
• link 目标版本：brew link php@8.1
• 确认符号链接：ls -l $(which php) 应指向 ../Cellar/php@8.1/...
• 更新 php.ini 路径：不同版本的配置文件在 /opt/homebrew/etc/php/8.1/、/opt/homebrew/etc/php/8.3/ 下，别改错地方

每次换版本后，所有扩展都得重新确认是否装对该版本，php-redis 这类 formula 默认只适配当前 php 主包，老版本需手动装 php@8.1-redis（如果存在）。

最易被忽略的是 Web 服务器和 CLI 使用两套 PHP 环境，调试时务必分清你在测哪个；另外 Homebrew 更新后可能自动升级 PHP 主包，导致 link 切换回新版，建议用 brew pin php@8.3 锁定版本。