PHP手动安装Brotli扩展详解

本文详细讲解了在PHP环境中手动安装Brotli扩展的完整流程与关键避坑指南，涵盖版本一致性校验（php/phpize/php-config三者主版本必须严格匹配）、源码克隆与编译（强调--recursive拉取子模块及libbrotli依赖处理）、扩展启用与路径配置、以及生产环境中极易被忽视的压缩启用逻辑和Nginx/PHP双层Brotli配置冲突问题；尤其提醒读者：仅加载扩展不等于自动压缩，需显式调用ini_set开启，并根据服务器架构（如是否由Nginx统一处理）合理分工，避免因重复压缩导致响应头混乱或客户端解压失败——这是一份兼顾实操性与深度运维意识的硬核教程。

确认PHP版本和phpize路径是否匹配

编译前不核对版本，大概率会遇到 phpize 报错或扩展加载失败。必须用当前运行的 PHP 对应的 phpize，而不是系统默认或旧版残留的。

执行以下命令确认：

which php
php -v
which phpize
phpize --version

三者输出的 PHP 主版本号（如 7.4、8.1、8.3）必须一致。若不一致，需切换到对应版本的 SCL 环境（如 CentOS/RHEL 的 scl enable php81 bash），或重新安装匹配的 php-devel 包。

下载并编译php-ext-brotli源码

直接克隆带子模块的完整仓库，避免后续因缺少 libbrotli 头文件导致 ./configure 失败：

git clone --recursive --depth=1 https://github.com/kjdev/php-ext-brotli.git
cd php-ext-brotli
phpize

执行 ./configure 时注意两点：

• 若系统已装 libbrotli-dev（Debian/Ubuntu）或 brotli-devel（RHEL/CentOS），可直接 ./configure
• 若提示 cannot find brotli library，说明 pkg-config 找不到库，需手动指定路径，例如：./configure --with-libbrotli=/usr/local/lib

接着执行：

make && sudo make install

成功后会输出类似 Installing shared extensions: /usr/lib64/php/modules/ 的路径，记下该路径，后面配 php.ini 时要用。

启用扩展并验证是否加载成功

在正确的 php.ini 中添加一行（不是 php.d/brotli.ini，除非你明确知道它被包含）：

extension=brotli.so

注意：brotli.so 文件名必须与 make install 输出的文件名完全一致；若路径不在默认扩展目录，需写绝对路径，例如：

extension=/usr/lib64/php/modules/brotli.so

重启 PHP-FPM 或 Apache 后，执行：

php -m | grep brotli
php -i | grep "brotli.output_compression"

若第一条无输出，说明未加载；若第二条返回 brotli.output_compression => 0 => 0，说明已加载但未启用压缩功能。

在代码中启用Brotli输出压缩

仅加载扩展不会自动压缩响应体，必须显式开启：

• 全局启用（推荐放在入口文件顶部，且不能有任何输出前）：ini_set('brotli.output_compression', 1);
• 设置压缩级别（0–11，默认 -1 相当于 11）：ini_set('brotli.output_compression_level', 6);
• 浏览器必须发送 Accept-Encoding: br，Nginx/Apache 才会透传；若用 Brotli + Nginx，brotli.output_compression 应设为 0，交由 Nginx 统一处理，否则可能重复压缩或冲突

验证是否生效：用 curl 查看响应头：curl -H "Accept-Encoding: br" -I https://yoursite.com/test.php，返回中应含 Content-Encoding: br 和 Vary: Accept-Encoding。

真正容易被忽略的是：Nginx 已启用了 Brotli，又在 PHP 层开了 brotli.output_compression，结果响应头混乱、客户端解压失败——这种叠加配置比没开还麻烦。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PHP手动安装Brotli扩展详解》文章吧，也可关注golang学习网公众号了解相关技术文章。