Composer 常规操作说明与问题处理

一、 Composer 简介，安装

Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖的代码库，它会在你的项目中为你安装他们。

Composer 将这样为你解决问题：

1. a) 你有一个项目依赖于若干个库。
2. b) 其中一些库依赖于其他库。
3. c) 你声明你所依赖的东西。
4. 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（生产环境依赖）

1. 用途：项目必须依赖的包，无论是开发环境还是生产环境都需要。

2. 安装方式：

   • composer install（默认安装）
   • composer require 包名（默认加入 require）

3. 典型场景：

   • 核心框架（如 laravel/framework）
   • 数据库驱动（如 doctrine/dbal）
   • HTTP 客户端（如 guzzlehttp/guzzle）
   • 项目运行所必需的库

3. require-dev（开发环境依赖）

1. 用途：仅在开发、测试或调试时需要的包，生产环境不需要。

2. 安装方式：

   • composer install --dev（默认安装）

   • composer require --dev 包名（加入 require-dev）

3. 典型场景：

   • 测试工具（如 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

参考文档：
https://docs.phpcomposer.com/