PHP 依赖管理

Begindev 编辑部 April 1, 2026

PHP 拥有海量的库、框架和组件可供选择。你的项目很可能会使用其中的好几个——这些就是项目的“依赖”。过去，PHP 并没有一个好的方式来管理这些依赖。即使你手动管理它们，仍然需要担心代码的自动加载问题。

现在，这已经不再是问题了。

目前 PHP 有两套主要的包管理系统：Composer 和 PEAR。Composer 是目前最流行的 PHP 包管理器；但在很长一段时间里，PEAR 曾是主要的管理工具。了解 PEAR 的历史很有好处，因为即使你从不使用它，也可能会在某些地方看到它的影子。

1. Composer 与 Packagist

Composer 是 PHP 社区推荐的依赖管理器。你只需要在一个名为 composer.json 的文件中列出项目的依赖，然后运行简单的命令，Composer 就会自动为你下载这些依赖，并帮你设置好代码的自动加载。

Composer 的地位类似于 Node.js 世界的 NPM，或者 Ruby 世界的 Bundler。

目前有海量的 PHP 库与 Composer 兼容，可以直接在项目中使用。这些“包”都列在 Packagist 上，它是 Composer 兼容库的官方仓库。

1.1 如何安装 Composer

下载 Composer 最安全的方式是遵循官方安装说明。这可以验证安装程序是否完整或被篡改。安装程序会在你当前的目录下生成一个 composer.phar 二进制文件。

我们建议将 Composer 安装为全局变量（例如在 /usr/local/bin 中保留一份副本）。安装完成后，运行以下命令：

# 将文件移动到全局可执行路径
mv composer.phar /usr/local/bin/composer

注意： 如果因为权限问题失败，请在命令前加上 sudo。

如果你是本地安装，运行方式是 php composer.phar；如果是全局安装，只需输入 composer。

1.2 在 Windows 上安装

对于 Windows 用户，最简单的方法是使用 ComposerSetup 安装程序。它会执行全局安装并自动设置 $PATH 环境变量，这样你就可以在命令行的任何目录下直接调用 composer。

1.3 如何定义和安装依赖

Composer 通过 composer.json 文件追踪项目的依赖。你可以手动编写它，也可以使用 Composer 自带的命令。

使用 composer require 命令可以添加依赖。如果你还没有 composer.json 文件，它会自动为你创建一个。以下是添加 Twig 模板引擎作为依赖的示例：

# 添加 Twig 作为项目依赖
composer require twig/twig:^2.0

另外，composer init 命令会引导你通过交互方式为项目创建完整的 composer.json 文件。无论采用哪种方式，一旦有了这个文件，你就可以告诉 Composer 将依赖下载并安装到 vendor/ 目录中：

# 安装 composer.json 中定义的全部依赖
composer install

接下来，在你应用程序的主 PHP 文件中添加下面这一行；这会告诉 PHP 为你的项目依赖使用 Composer 的自动加载器：

<?php
// 引入 Composer 自动加载器
require 'vendor/autoload.php';

现在你可以直接使用那些依赖库了，它们会在需要时被自动加载。

1.4 更新你的依赖

当你第一次运行 composer install 时，Composer 会创建一个名为 composer.lock 的文件。它记录了当时下载的每个包的精确版本。

团队协作： 如果你把项目分享给其他人，请务必包含 composer.lock 文件。这样当他们运行 composer install 时，得到的版本会和你完全一致。
更新： 要更新你的依赖，请运行 composer update。
注意： 在部署到生产环境时，千万不要运行 composer update，只能运行 composer install，否则生产环境的包版本可能与你本地不一致。

如果你的版本要求定义得比较灵活（例如 ~1.8 代表“大于 1.8.0 且小于 2.0.x”），composer update 就会根据你的限制将包升级到最新版。

1.5 更新通知

如果你想接收新版本发布的通知，可以注册 libraries.io，这项服务可以监控你的依赖并在有更新时发送提醒。

1.6 检查依赖的安全性

Local PHP Security Checker 是一个命令行工具，它会检查你的 composer.lock 文件，告诉你是否有任何依赖需要因为安全漏洞而更新。

1.7 使用 Composer 处理全局依赖

Composer 也可以处理全局依赖及其二进制工具。用法很简单，只需在命令前加上 global 即可。例如，如果你想在全局范围内安装 PHPUnit：

# 全局安装 PHPUnit
composer global require phpunit/phpunit

这会创建一个 ~/.composer 文件夹来存放全局依赖。为了让这些工具在任何地方都能运行，你需要将 ~/.composer/vendor/bin 文件夹添加到你的系统 $PATH 变量中。

2. PEAR

PEAR 是一款资深的包管理器，部分 PHP 开发者仍然喜欢使用它。它的行为与 Composer 类似，但有一些显著区别：

结构限制： PEAR 要求每个包必须符合特定的结构。这意味着包作者必须专门为 PEAR 准备代码。你无法直接使用一个没有为 PEAR 适配过的项目。
全局安装： PEAR 将包安装在全局。这意味着安装一次后，服务器上的所有项目都可以使用。如果多个项目依赖同一个包的同一个版本，这很好；但如果两个项目需要不同的版本，就会产生冲突。

2.1 如何安装 PEAR

你可以通过下载 .phar 安装程序并执行来安装 PEAR。PEAR 官方文档针对不同操作系统提供了详细的安装说明。

如果你使用 Linux，也可以查看发行版的包管理器。例如，Debian 和 Ubuntu 都有 php-pear 软件包。

2.2 如何安装一个包

如果该包列在 PEAR 官方列表上，你可以通过指定名称来安装：

# 安装名为 foo 的包
pear install foo

如果包托管在其他“频道”（Channel）上，你需要先 discover（发现）该频道。更多信息请参考 PEAR 的频道使用文档。

3. 在 Composer 中处理 PEAR 依赖

如果你已经在使用 Composer，但也想安装一些 PEAR 的代码，你可以让 Composer 来接管 PEAR 依赖。由于 Composer 2 版本不再直接支持 PEAR 仓库，你需要手动添加仓库配置来安装 PEAR 包：

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "pear2/pear2-http-request",
                "version": "2.5.1",
                "dist": {
                    "url": "https://github.com/pear2/HTTP_Request/archive/refs/heads/master.zip",
                    "type": "zip"
                }
            }
        }
    ],
    "require": {
        "pear2/pear2-http-request": "*"
    },
    "autoload": {
        "psr-4": {"PEAR2\\HTTP\\": "vendor/pear2/pear2-http-request/src/HTTP/"}
    }
}

在上面的配置中：

repositories 部分告诉 Composer 具体的包来源。
require 部分引用该包。

安装完成后，该代码将出现在你的 vendor 目录中，并通过 Composer 的自动加载器自动生效。路径通常如下：
vendor/pear2/pear2-http-request/pear2/HTTP/Request.php

要使用这个 PEAR 包，只需像下面这样引用即可：

<?php
// 引入 Composer 自动加载
require __DIR__ . '/vendor/autoload.php';

// 使用 PEAR2 的命名空间
use PEAR2\HTTP\Request;

$request = new Request();