如何用Composer管理PHP项目依赖？

wen PHP项目 2026-06-19 2

本文目录导读：

第一步：安装 Composer
第二步：初始化项目
第三步：安装依赖包
第四步：自动加载
第五步：更新依赖
第六步：管理依赖的版本控制（重要）
常见操作速查表

如何使用 Composer 管理 PHP 项目依赖——这是现代 PHP 开发的必备技能，下面我为你梳理一套完整、清晰的操作流程和最佳实践。

第一步：安装 Composer

全局安装（推荐）：
- macOS / Linux：
```
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer
```
  之后，在终端输入 composer 即可验证。
- Windows：下载并运行 Composer-Setup.exe，安装器会自动配置系统路径，安装完成后，打开 PowerShell 或 CMD，输入 composer 测试。
检查版本：
```
composer --version
```

第二步：初始化项目

进入你的 PHP 项目根目录（/my-project）,运行：

composer init

这个命令会以交互式问答方式引导你创建 composer.json 文件（最核心的配置文件）,你需要填写：

Package name：包名，格式为 vendor/package（mycompany/my-app）。
Description：项目描述。
Author：作者信息。
Minimum Stability：依赖库的最低稳定性（建议先选 stable）。
Package Type：类型（通常是 project 或 library）。
License：许可证类型。

如果你不想交互，可以直接创建一个最简单的 composer.json：

{
    "name": "your-vendor/your-project",
    "require": {}
}

第三步：安装依赖包

安装普通依赖（生产环境）

composer require monolog/monolog

作用：安装 monolog/monolog 日志库。
效果：
- 自动修改 composer.json，在 require 部分添加 "monolog/monolog": "^2.0"。
- 下载包到 vendor/ 目录。
- 自动生成 composer.lock 锁文件。

你还可以指定版本：

composer require monolog/monolog:1.26.0

安装开发依赖（仅本地或测试环境）

composer require --dev phpunit/phpunit

作用：安装 PHPUnit 测试框架。
效果：添加到 composer.json 的 require-dev 部分，composer install --no-dev 时不会安装。

从 `composer.json` 安装所有依赖

composer install

作用：当项目已经存在 composer.json（或从 Git 拉取后）时使用。
关键行为：
- 如果存在 composer.lock，则安装锁文件中的确切版本（确保团队一致性）。
- 如果不存在 composer.lock,则解析最新兼容版本并生成锁文件。

第四步：自动加载

Composer 自动生成 vendor/autoload.php 文件，在你的项目入口文件（index.php）顶部添加：

<?php
require __DIR__ . '/vendor/autoload.php';
// 现在你可以直接使用所有已安装的库
$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('这是一个警告日志');

自定义自动加载：你还可以在 composer.json 中配置项目的命名空间自动加载：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

配置后，运行 composer dump-autoload 刷新自动加载映射，之后，src/ 目录下的类（src/Controllers/HomeController.php 中命名空间为 App\Controllers）就能被自动加载了。

第五步：更新依赖

composer update

作用：根据 composer.json 中的版本约束，将依赖更新到最新的兼容版本，并更新 composer.lock。
注意：不要在正式部署时运行 composer update（你会得到不确定的版本），使用 composer install 来安装锁文件中的固定版本。

更新单个包：

composer update monolog/monolog

第六步：管理依赖的版本控制（重要）

你应该将以下文件提交到 Git（或其它版本控制系统）：

文件	是否提交	原因
`composer.json`	✅ 必须	定义项目依赖配置
`composer.lock`	✅ 必须	锁定确切版本，保证团队和部署环境一致性
`vendor/`	❌ 忽略	依赖包体积大，且每次安装版本可还原

在 .gitignore 中添加：

vendor/

其他人克隆项目后，只需运行 composer install 即可获得与开发环境完全一致的依赖。

常见操作速查表

命令	用途
`composer init`	初始化项目，生成 `composer.json`
`composer install`	安装依赖（根据 `composer.lock`）
`composer update`	更新依赖（修改 `composer.lock`）
`composer require <包名>`	安装并记录依赖
`composer remove <包名>`	移除依赖
`composer dump-autoload`	重新生成自动加载文件
`composer search <关键词>`	搜索可用包
`composer show`	查看已安装的包及版本
`composer validate`	检查 `composer.json` 的有效性

始终提交 composer.lock：确保团队成员和部署环境使用完全相同的版本。
区分依赖环境：生产依赖用 require，开发工具用 require --dev。
合理版本约束：
- ^1.0：允许 1.x 的大版本更新（最常用）。
- ~1.2：允许 1.2.x 的小版本更新。
- 0.*：允许 1.0.x 的补丁更新。
- 允许任何版本（不推荐，可能导致意外破坏）。
生产部署使用 --no-dev：
```
composer install --no-dev --optimize-autoloader
```
这会跳过开发依赖,并生成更高效的类映射加载器。
定期更新依赖：每隔一段时间运行 composer outdated 查看哪些包有更新，然后有计划地执行 composer update（建议逐包更新）。