21CTO导读：本篇文章将向你介绍 PIE，这是一款由 PHP Foundation 推出的官方 PHP 扩展安装工具，正式取代已声明弃用的 PECL。

pecl install redis

重温什么是PHP扩展？

PHP 扩展是用 C 语言编写的模块，它们为 PHP 语言本身添加新功能。有些扩展随 PHP 一起提供（例如intl、gd或pdo_mysql），而另一些则需要单独安装，例如redis用于 Redis 数据库、imagick图像处理或xdebug调试扩展等。

对于第二种扩展，到目前为止的主要工具一直是 PECL。

什么是PIE？

PIE 是PHP 基金会开发的官方 PHP 扩展安装程序。它的工作方式与 Composer 很相似，均以 PHAR 文件的形式分发，并使用 Packagist 来查找软件包。

不同之处在于，PIE 不是将 PHP 库引入你的项目，而是将扩展编译并安装到 PHP 安装目录本身。

2025年，PHP社区就“推荐使用PIE并弃用PECL”的RFC提案进行了投票，该提案以36票赞成、0票反对获得通过。

图源：https://wiki.php.net/rfc/adopt_pie_deprecate_pecl

从此以后，PIE便正式成为安装扩展的推荐方式，而PECL则被宣布弃用。

不过，PECL目前仍然可用，但已经不再被官方推荐使用，未来的RFC提案将决定何时将其移除。

截至撰写本文时，PIE 的最新版本为1.5.3，发布于 2026 年 10 月 21 日。

安装扩展程序的老方法

为了更好地理解 PIE，让我们先回顾一下目前为止使用的命令行和工具。

PECL

PECL（The PHP Extension Community Library，PHP扩展社区库）是一个基于PEAR的同名代码库和工具。安装过程很简单，例如：

pecl install redis

但实际上，还是存在一些不便之处：

enable igbinary serializer support? [no] :enable lzf compression support? [no] :enable zstd compression support? [no] :enable msgpack serializer support? [no] :enable lz4 compression? [no] :use system liblz4? [yes] :

你需要依次回答这些问题，如果选择默认值，也要敲一下回车。

接下来，我们需要做的事情：

• 手动启用
  

• 一个独立的仓库
  

• 没有描述项目定义
  

docker-php-ext-install命令

官方的 PHP Docker 镜像自带一些辅助脚本，例如 `pyconfig` docker-php-ext-install。但是，它们只能与 PHP 源代码中包含的扩展（例如 `pyconfig`intl或 `pyconfig` pdo_mysql）一起使用。对于 Redis、Xdebug 和其他外部扩展，我们仍然需要使用 PECL：

RUN docker-php-ext-install intl pdo_mysql \    && pecl install redis \    && docker-php-ext-enable redis

操作系统软件包

在 Debian 和 Ubuntu 系统中，我们可以将扩展程序作为软件包安装，例如从 Ondřej Surý 的软件仓库 (deb.sury.org) 下载。

这很方便，但它仅适用于由同一来源构建的 PHP 版本，并且你还必须依赖已打包的扩展程序及其版本。

手工编译

最后一种方法是下载源代码，并运行如下类似命令：


phpize `config ./configure/ make...make install php.ini

如何安装 PIE

运行 PIE需要PHP 8.1 或更高版本，但 PIE 本身也可以为你的系统安装其他 PHP 版本的扩展。

在 Linux 和 macOS 系统上，以下命令会下载 PIE，验证其真实性，并将其放置在/usr/local/bin/pie：

curl -fL --output /tmp/pie.phar \  https://github.com/php/pie/releases/latest/download/pie.phar \  && gh attestation verify --owner php /tmp/pie.phar \  && sudo mv /tmp/pie.phar /usr/local/bin/pie \  && sudo chmod +x /usr/local/bin/pie

这里的gh attestation verify步骤需要使用 GitHub CLI。它会确认该文件确实由 PHP 团队发布。

如何使用PIE

扩展程序会像 Composer 一样，通过 Packagist 名称进行安装：

pie install phpredis/phpredis

以下是 PIE 在干净的 Docker 镜像（包含 PHP 8.5）上进行测试时输出的结果：

🥧 PHP Installer for Extensions (PIE) 1.5.3, from The PHP FoundationYou are running PHP 8.5.12Target PHP installation: 8.5.12 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)Found package: phpredis/phpredis:6.3.0 which provides ext-redisphpize complete.Configure complete with options: --with-php-config=/usr/local/bin/php-configBuild complete: .../phpredis/phpredis/modules/redis.soInstall complete: /usr/local/lib/php/extensions/no-debug-non-zts-20250925/redis.so✅ Extension phpredis/phpredis:6.3.0 is enabled and loaded in /usr/local/bin/php

请注意最后一行，PIE 不仅编译并安装扩展程序，还会自动启用它，这样我们无需再到处查找php.ini。

如若你不知道确切的软件包名称，可以用以下命令搜索一下：

pie search xdebug

以下是一些其他有用的命令：

• pie info vendor/package– 显示有关扩展程序及其可编译选项的信息。
• pie show– 列出随 PIE 安装的扩展程序。
• pie upgrade– 更新所有随 PIE 安装的扩展程序，使其版本与安装时版本保持一致。
• pie download仅pie build下载或下载并编译扩展程序，而不进行安装。
• pie check-build-tools– 检查您是否拥有编译扩展所需的工具（gcc、make、autoconf 等）。

可选择版本，就像Composer一样

我们可以使用与 Composer 相同的语法来锁定扩展程序的版本：

pie install xdebug/xdebug:^3.4

如果缺少构建工具，PIE 会提示我们安装。PECL 以交互方式询问的构建选项会直接作为参数传递到这里。

你还可以使用以下命令查看可用选项列表：


pie info

最佳功能：适用于整个项目的扩展

现在说的正是 PIE 的真正优势所在。比如Composer 已经知道你的项目需要哪些扩展，它们列在composer.json中的ext-*部分：

{    "name": "jumpbg/blog-demo",    "require": {        "php": "^8.4",        "ext-redis": "^6.0",        "ext-intl": "*"    }}

使用pie install时，如果在项目文件夹内且不带任何参数运行， PIE 会检查缺少哪些扩展，并提供安装选项。

以下是我们的测试结果（在 CI 或 Docker 环境中，由于无人响应提示，你需要自行选择--select）：

pie install --select redis=phpredis/phpredis

Checking extensions for your project jumpbg/blog-demo (path: /app)requires: ext-intl:* 🚫 MissingPIE could not find any potential matches for ext-intl; if you know which package to use, specify --select extension=vendor/package in the `pie install` options.requires: ext-redis:^6.0 🚫 MissingFound package: phpredis/phpredis:6.3.0 which provides ext-redis...✅ Extension phpredis/phpredis:6.3.0 is enabled and loaded in /usr/local/bin/phpFinished checking extensions.

如你所见，PIE 已安装redis，但未找到intl。

重要说明

在官方 Docker 镜像中，PHP 源代码附带的扩展（例如 intl）仍然通过 docker-php-ext-install 启用。

如果你使用pie.json和pie.lock文件，PIE 也可以安装完全相同的锁定版本pie install --from-lock。

Docker 中的 PIE

PIE 还发布了一个仅包含 PHAR 文件的 Docker 镜像。你可以仅在构建过程中挂载该镜像，这样 PIE 就不会出现在最终镜像中。此 Dockerfile 在官方 PHP 8.5 镜像上安装了 Redis，我们对其进行了测试：

FROM php:8.5-cliRUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \    apt-get update \    && apt-get install -y --no-install-recommends unzip \    && pie install phpredis/phpredis \    && rm -rf /var/lib/apt/lists/*

PIE 需要unzip（或 Zip 扩展）来提取源代码，这和 Composer 一样。

Windows 上的 PIE

在 Windows 系统中，扩展程序通常无需编译，而是以现成的 DLL 文件形式分发。

PIE 利用了这一点：它会下载与你的 PHP 版本相匹配的 DLL 文件，并将其放置在扩展程序文件夹中。

我们不需要安装任何编译工具。

PECL 与 PIE

以下是PECL和PIC主要区别与对比：

如果你熟悉 PECL 的命令，以下表格是它们的等效命令：

哪些扩展程序支持 PIE？

许多最流行的扩展程序已经支持 PIE，包括xdebug/xdebug、phpredis/phpredis和apcu/apcu、imagick/imagick、mongodb/mongodb-extension、php-memcached/php-memcached、swoole/swoole、pecl/pcovopen、telemetry/ext-opentelemetry等知名或有用的扩展库。

我们可以在packagist.org/extensions上找到完整的列表。


如果你正维护一个扩展，也可以添加 PIE 支持。它类似于发布常规 Composer 包：添加一个composer.json类型为php-ext（或php-ext-zendZend 扩展）的包，然后在 Packagist 上发布该包，并使用 Git 标签发布新版本。

结语

PIE 之于 PHP 扩展，正如 Composer 多年前之于 PHP 库，它为开发者提供了一种熟悉的方式来查找、安装和更新扩展，包括显示版本信息，无需php.ini手动编辑等方便特性。

它还能够通过一条命令安装项目中所有缺失的扩展，对于本地开发、持续集成 (CI) 和 Docker 来说尤其方便。到现在为止，PECL 仍然是可用的，但如果你正在启动一个新项目或更新 Dockerfile，建议现在就切换到 PIE。

作者：洛逸