Composer 常規操作說明與問題處理

一、 Composer 簡介，安裝
二、全局配置
三、項目配置（composer.json）
- 3.1 composer.json 文件
- - 1. 基礎字段信息
  - 2. **require（`生產環境依賴`）**
  - 3. **require-dev（`開發環境依賴`）**
- 3.2 composer.lock 文件
- - 1. 文件作用
  - 2. 文件生成與更新
  - 3. 關鍵規則
四、項目安裝依賴
- 1.安裝所有依賴（開發+生產）
- 2.僅安裝生產環境依賴（生產環境必備）
- 3.驗證安裝結果
五. 關鍵注意事項
- 1.`composer.lock` 的作用
- 2. 自動加載優化（`生產環境必備`）
- 3. `composer install --ignore-platform-reqs` 在生產環境中禁止使用
- 4. compose update，install，require 理解后使用
六常見問題
- 1：依賴安裝失敗或版本沖突
- 2：切換倉庫源或鏡像
- 3. 依賴沖突（Dependency Resolution）
- 4：檢查環境缺失項

一、 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

參考文檔：
https://docs.phpcomposer.com/