一、 Composer 简介,安装
Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖的代码库,它会在你的项目中为你安装他们。
Composer 将这样为你解决问题:
- a) 你有一个项目依赖于若干个库。
- b) 其中一些库依赖于其他库。
- c) 你声明你所依赖的东西。
- d) Composer 会找出哪个版本的包需要安装,并安装它们(将它们下载到你的项目中)。
全局安装,linux
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
window安装或局部安装,暂不说明,自己去官网解决即可
二、全局配置
全局配置存储在用户目录下的 ~/.config/composer/config.json
(Linux/macOS)或 %APPDATA%\Composer\config.json
(Windows)。
常用全局配置
# 查看当前全局配置
composer config -g --list
# 编辑全局配置(手动修改文件)
composer config -g --editor
# 清除缓存
composer clear-cache
# 设置全局仓库镜像(如阿里云)
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
# 设置全局最低稳定性
composer config -g minimum-stability dev
# 设置全局HTTP超时时间
composer config -g process-timeout 600
我经常使用的是就设置镜像,其他基本上很少用到。
三、项目配置(composer.json)
3.1 composer.json 文件
composer.json 是 PHP 项目依赖管理的核心配置文件
,用于:
-
定义项目元数据(名称、版本、作者等)
-
声明生产/开发环境依赖
-
配置自动加载规则
-
定义脚本钩子(如安装后操作)
-
控制包安装行为
其文件位置是在项目根目录
下面
{
"name": "example/project",
"description": "A sample project",
"type": "project",
"license": "MIT",
"require": {
"php": "^8.0",
"ext-json": "*",
"monolog/monolog": "^2.0"
},
"require-dev": {
"phpunit/phpunit": "^9.0"
},
"autoload": {
"psr-4": {
"App\\": "app/",
"Database\\Factories\\": "database/factories/",
"Database\\Seeders\\": "database/seeders/"
},
"files": [
"app/Helpers/functions.php"
],
"classmap": [
"app/Legacy/", // 直接指定目录
"lib/old-class.php" // 直接指定单个文件
]
},
"autoload-dev": {
"psr-4": {
"Tests\\": "tests/"
}
},
//最小稳定性
//可用的稳定性标识(按字母排序):dev、alpha、beta、RC、stable
"minimum-stability": "stable",
"prefer-stable": true
}
1. 基础字段信息
- autoload / classmap
-
是 Composer 提供的一种 后备自动加载机制,用于加载不符合 PSR-0/PSR-4 标准的类
-
加载
无命名空间
的类:适用于传统代码或第三方库中未使用命名空间的类。 -
兼容
非标准目录
结构:当文件路径与类名/命名空间不匹配 PSR-4 规则时。 -
性能优化:生成类路径映射表,避免运行时文件扫描(适合生产环境)。
-
2. require(生产环境依赖
)
-
用途:项目
必须依赖
的包,无论是开发环境还是生产环境都需要
。 -
安装方式:
- composer install(默认安装)
- composer require 包名(默认加入 require)
-
典型场景:
- 核心框架(如 laravel/framework)
- 数据库驱动(如 doctrine/dbal)
- HTTP 客户端(如 guzzlehttp/guzzle)
- 项目运行所必需的库
3. require-dev(开发环境依赖
)
-
用途:仅在开发、测试或调试时需要的包,
生产环境不需要
。 -
安装方式:
-
composer install --dev(默认安装)
-
composer require --dev 包名(加入 require-dev)
-
-
典型场景:
-
测试工具(如 phpunit/phpunit)
-
代码静态分析(如 phpstan/phpstan)
-
安全检查(如 roave/security-advisories)
-
本地开发辅助工具(如 barryvdh/laravel-debugbar)
-
3.2 composer.lock 文件
composer.lock 是 Composer 自动生成的核心文件,用于精确锁定依赖版本
,确保项目在不同环境
中使用完全一致
的依赖树
1. 文件作用
-
版本锁定:记录所有依赖包(包括间接依赖)的精确版本号(如 1.2.3),而非 composer.json 中的模糊约束(如 ^1.0)。
-
哈希校验:存储包的哈希值(SHA-1),确保下载的包未被篡改。
-
依赖树固化:避免因依赖更新导致意外行为(如间接依赖升级引发兼容性问题)。
2. 文件生成与更新
-
首次运行 composer install 时自动生成。
-
运行 composer update 时更新。
3. 关键规则
(1) 必须提交到版本控制
(如 Git)
-
确保团队其他成员和生产环境使用完全一致的依赖版本
。 -
避免因 composer.json 的版本范围(如 ^1.0)在不同时间安装不同版本导致差异。
(2) 不要手动修改
- 所有变更应通过 Composer 命令自动完成:
- 更新依赖:composer update
- 新增依赖:composer require vendor/package
(3) 安装依赖时优先使用 lock 文件
- 运行 composer install 时:
- 如果存在 composer.lock,则严格安装其中指定的版本。
- 如果不存在 composer.lock,则根据 composer.json 安装并生成新锁文件。
四、项目安装依赖
1.安装所有依赖(开发+生产)
composer install
作用:
-
读取 composer.json 中的依赖声明,安装所有需要的包(
生产环境 + 开发环境
)。 -
生成/更新
composer.lock
文件(锁定具体版本)。 -
执行
autoload
配置,生成类自动加载文件(如 vendor/autoload.php)。
2.仅安装生产环境依赖(生产环境必备)
composer install --no-dev --optimize-autoloader
- 生产环境部署时
- –no-dev 跳过开发依赖(如测试工具、调试包)
- –optimize-autoloader:生成类映射表,提升自动加载性能(适合生产环境)。
- –classmap-authoritative:进一步优化,但禁用 PSR-0 自动发现(极端优化场景使用)。
3.验证安装结果
-
检查 vendor 目录:确认依赖已下载。
-
检查 composer.lock:确认版本已锁定。
-
引入自动加载文件(在代码中):
require __DIR__ . '/vendor/autoload.php';
五. 关键注意事项
1.composer.lock
的作用
- 必须提交到版本控制(如 Git):
- 确保团队其他成员和生产环境使用完全一致的依赖版本。
- 不要手动修改它:该文件由 Composer 自动维护。
2. 自动加载优化(生产环境必备
)
composer install --no-dev --optimize-autoloader
3. composer install --ignore-platform-reqs
在生产环境中禁止使用
-
–ignore-platform-reqs 会跳过以下检查:
-
PHP版本要求(如包要求 PHP 8.1,但当前是 PHP 7.4)
-
PHP扩展依赖(如 ext-json、ext-mbstring 等)
-
系统库依赖(如 lib-curl)
-
-
由于会忽略以上的检查,导致应用在运行时,因
缺少扩展
或版本不兼容
导致运行时错误 -
优先修复环境,而非忽略检查!
4. compose update,install,require 理解后使用
-
composer
install
根据composer.lock
文件安装
精确版本的依赖(如果 lock 文件不存在,则根据 composer.json 生成它) -
composer
update
根据composer.json
的版本约束,更新依赖
到最新兼容版本,并更新
composer.lock。-
composer update vendor/package # 仅更新指定包
-
composer update(无参数) 可能意外升级大量包,破坏稳定性,
慎用全局更新
-
-
composer
require
新增依赖包
,并自动更新 composer.json 和 composer.lock。
六 常见问题
1:依赖安装失败或版本冲突
问题表现:执行 composer install 或 update 时出现奇怪错误(如找不到包、版本不匹配)。
原因:Composer 的本地缓存可能损坏或过期(缓存了错误的包元数据)。
解决:
composer clear-cache
composer install # 重新安装
2:切换仓库源或镜像
问题表现:更换了 Composer 镜像源(如从官方源切换到阿里云),但安装时仍从旧源拉取包。
原因:旧的仓库元数据被缓存。
解决:
composer clear-cache
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
composer install
3. 依赖冲突(Dependency Resolution)
问题表现: Your requirements could not be resolved to an installable set of packages.
查看冲突原因:
composer why vendor/package # 查看某个包被引入的原因
composer depends guzzlehttp/guzzle # 检查包依赖关系
4:检查环境缺失项
# 列出不满足的环境要求
composer check-platform-reqs