PECL 时代落幕

2025 年 8 月，PHP 内部社区提交了一份 RFC（Recommend PIE and deprecate PECL）。该 RFC 于 2025 年 9 月 20 日投票通过，状态标记为 Accepted。PECL 作为 PHP 生态中运行二十余年的扩展分发与安装渠道，自此正式进入弃用状态。

PECL 官网首页现已挂出弃用横幅：

PECL is deprecated. PHP Installer for Extensions (PIE) is the replacement for PECL. We recommend publishing your extension using PIE instead.

RFC 明确：这不是"立即拔电源"式的关闭——PECL 网站和 CLI 工具目前仍会继续运行，不会产生向后不兼容的破坏。但 PECL 的 REST 元数据接口正在逐步下线，这一变动已开始对全球范围内的 PHP 项目产生直接冲击，其中 Docker 镜像构建场景受影响最为广泛。

本地 Docker 构建失效

传统的 pecl install 命令安装扩展时，第一步会向 PECL 官方的 REST 接口请求扩展版本、校验信息等 XML 元数据。随着接口下线，这一步骤直接失败，最典型的报错如下：

Package "xlswriter" does not have REST info xml available

该错误的底层逻辑是：元数据请求返回空内容，后续匹配校验操作因无有效结果返回退出码 1，最终导致安装流程强制终止。

这一问题在 Docker 容器构建 场景中爆发得尤为集中。官方 PHP 镜像长期将 pecl install + docker-php-ext-enable 作为第三方扩展的标准安装范式，大量项目的 Dockerfile、CI/CD 构建流水线都依赖这套成熟逻辑。

以常用的 xlswriter 扩展为例，许多开发者在镜像构建时突然遭遇流程中断：即便部分团队已提前将 xlswriter-1.5.5.tgz 源码包本地化缓存，只要安装脚本仍依赖 PECL 通道的元数据校验机制，就无法跳过 REST 接口校验完成安装，最终导致整个镜像构建失败。

PHP 官方明确给出了替代方向：PHP Installer for Extensions（PIE）是 PECL 的官方继任者，推荐所有扩展开发者与使用者迁移至 PIE 体系。

下一代 PHP 扩展安装器 PIE

PIE（PHP Installer for Extensions）是由 PHP 基金会推出的全新扩展安装工具，定位为 PECL 的官方替代品。它以 PHAR 文件形式分发，使用体验与 Composer 高度相似，但职责边界不同：

• Composer：在项目层面安装 PHP 代码包，管理项目依赖
• PIE：在系统层面安装 PHP 扩展（PHP Modules / Zend Extensions），管理运行时能力

核心特性

1. 跨版本兼容能力强

• 运行 PIE 本身仅需 PHP 8.1 及以上版本
• 支持向本机任意已安装的 PHP 版本安装扩展，向下兼容覆盖更广

2. 跨平台一致体验

• Linux/macOS：自动调用 phpize、./configure、make 完成源码编译安装，需提前配备 autoconf、automake、libtool、m4、make、gcc 以及 phpize、php-config（或 Debian 系的 php-dev 包）等编译工具链。自 PIE 1.4.0 起，缺失的构建工具可自动检测并安装
• Windows：直接分发预编译 DLL 包，无需本地编译环境

3. 与 Packagist 生态打通支持 PIE 的扩展可在 packagist.org/extensions 列表中查询，扩展分发正式纳入 Composer 生态体系，不再依赖独立的 PECL 渠道。

4. 项目级扩展依赖检测在项目目录下直接执行 pie install，可自动扫描 composer.json 中声明的 ext-* 扩展依赖，检测缺失项并引导安装，实现从代码依赖到系统扩展的一体化管理。

5. 自动启用扩展PIE 安装扩展后会自动尝试启用，无需手动编辑 php.ini。启用策略依次尝试：phpenmod（deb.sury.org 发行版）、docker-php-ext-enable（Docker PHP 镜像）、写入 additional .ini 文件、追加到 php.ini。如需跳过自动启用，可传 --skip-enable-extension 参数。

从 PECL 到 PIE 的落地方案

针对当前 PECL 接口逐步下线的现状，我们提供两套落地方案：过渡期应急方案可快速修复构建故障，长期方案则按照官方指引迁移至 PIE 体系。

过渡期应急：源码编译绕过 PECL（适用于尚未适配 PIE 的扩展）

如果目标扩展暂未适配 PIE，可直接下载官方源码包手动编译安装，完全绕开 PECL 的 REST 元数据接口，可立即修复 Docker 构建失败问题。该方案仅绕过元数据校验，仍使用官方发布的源码包，安全性与原 pecl install 一致。

注意：PECL 的 get 文件下载端点与 REST 元数据接口是独立服务。RFC 明确 PECL 网站目前仍继续运行，过渡期内 pecl.php.net/get/ 下载仍可用，但长期看应迁移至 PIE。

以下以 xlswriter 1.5.5 为例，给出 Dockerfile 完整示例：

FROM php:8.2-fpm# 安装系统编译依赖与扩展依赖库RUN apt-get update && apt-get install -y --no-install-recommends \    gcc make autoconf libz-dev pkg-config \    && rm -rf /var/lib/apt/lists/*# 下载指定版本源码包，手动编译安装（绕过 PECL REST 接口）RUN curl -fsSL https://pecl.php.net/get/xlswriter-1.5.5.tgz -o xlswriter.tgz \    && mkdir -p /tmp/xlswriter \    && tar -xf xlswriter.tgz -C /tmp/xlswriter --strip-components=1 \    && rm xlswriter.tgz \    && cd /tmp/xlswriter \    && phpize \    && ./configure --enable-xlswriter \    && make -j$(nproc) \    && make install \    && rm -rf /tmp/xlswriter# 启用扩展RUN docker-php-ext-enable xlswriter

注意：不同扩展有不同的系统依赖，编译前需确认依赖库已安装，例如 xlswriter 依赖 zlib 库，需提前安装 libz-dev 包。

长期方案：全面迁移至 PIE

按照 PHP 官方规划，PIE 是未来 PHP 扩展安装的标准工具。长期维护的项目建议逐步将构建脚本迁移至 PIE 体系，适配新的生态规范。

前提：目标扩展已适配 PIE 规范并发布到 Packagist 扩展频道。可在 packagist.org/extensions 查询适配状态。以 xlswriter 为例，它已在 PIE 支持列表中（包名 viest/xlswriter），可直接用 PIE 安装。

通用环境安装 PIE

手动安装方式与 Composer 一致：

1. 下载 pie.phar 文件（可选择稳定版或每日构建版）
2. 可选：通过 GitHub Attestation 校验文件来源

gh attestation verify --owner php pie.phar

1. 移动到系统 PATH 目录以便全局调用

sudo mv pie.phar /usr/local/bin/piesudo chmod +x /usr/local/bin/pie

macOS 也可通过 Homebrew 安装：brew install pie。Fedora / Enterprise Linux 10（需启用 EPEL）可执行 sudo dnf install pie。

常用操作命令

安装单个扩展（按 vendor/package 格式指定）：

pie install viest/xlswriter

PIE 安装完成后会自动启用扩展，无需手动编辑 php.ini。如果自动启用未生效，再手动添加：

extension=xlswriter

指定版本约束（语法与 Composer 一致）：

pie install xdebug/xdebug:^3.4.3

为其他 PHP 版本安装扩展：

pie install --with-php-config=/usr/bin/php-config7.2 my/extension

批量安装项目依赖扩展：进入项目根目录直接执行 pie install，工具会自动扫描 composer.json 中的扩展依赖，检测缺失项并引导安装。CI / 容器等非交互环境需用 --select 显式指定：

pie install \  --select example_pie_extension=asgrim/example-pie-extension \  --select redis=phpredis/phpredis

Docker 环境集成 PIE

官方推荐使用 binary-only 镜像引入 PIE，而非 curl 下载：

FROM php:8.2-fpm# 安装系统编译工具链与 unzip（PIE 解压依赖）RUN apt-get update && apt-get install -y --no-install-recommends \    gcc make autoconf libtool pkg-config libz-dev unzip \    && rm -rf /var/lib/apt/lists/*# 从官方 binary-only 镜像拷贝 pie.pharCOPY --from=ghcr.io/php/pie:bin /pie /usr/local/bin/pie# 通过 PIE 安装已适配的扩展（PIE 会自动调用 docker-php-ext-enable 启用）RUN pie install --no-cache --auto-install-build-tools viest/xlswriter

关键点：

• ghcr.io/php/pie:bin 镜像只提供 PHAR 文件，不含 PHP 运行时，运行时依赖（PHP 8.1+）由基础镜像提供。
• 标签 bin 是最新稳定版，也可用 1.5.0-bin 等固定版本。
• PIE 检测到 Docker PHP 镜像环境后会自动调用 docker-php-ext-enable，无需手动执行。
• --auto-install-build-tools 在非交互环境中自动安装缺失的编译工具。
• 如需安装多个扩展：pie install viest/xlswriter phpredis/phpredis（PIE 1.5+ 支持批量安装）。

小结

PECL 的弃用是 PHP 生态演进的必然结果。PIE 作为官方指定的继任者，继承了 Composer 生态的工程化优势，统一了代码包与扩展的分发体验，也解决了 PECL 多年来接口陈旧、维护不足、生态割裂的问题。

对于使用者而言，如果你仍在依赖 pecl install 完成扩展安装，尤其是 Docker 构建、CI/CD 流水线等自动化场景，需要尽快评估影响并调整构建脚本。对于扩展维护者，尽快适配 PIE 发布规范，才能确保你的扩展在新生态中持续可用。

更多详情可参考官方仓库：https://github.com/php/pie

webman docker 镜像

当然啦，最新版本的 webman docker 镜像也是基于 PIE 安装构建的哦！

拉取使用

docker run \  --rm \  -it \  -p 8787:8787 \  -v /home/www/webman:/app \  tinywan/docker-php-webman

仓库：https://github.com/Tinywan/docker-php-webman