Composer 基本命令

Composer 提供了丰富的命令行工具来管理 PHP 项目的依赖、自动加载、脚本执行等。掌握这些命令是日常 PHP 开发的基本功。本节将详细介绍最常用的 Composer 命令，每个命令都配有实际代码示例和使用场景说明。

前置知识

在阅读本节之前，你需要了解：

• Composer 已安装并配置（参见 Composer 安装）
• composer.json 的基本结构（参见 composer.json 配置）
• 终端 / 命令行基本操作

install — 安装依赖

composer install 是最常用的 Composer 命令，它会根据 composer.lock 文件（或 composer.json）安装所有声明的依赖。

# 基本用法：安装所有依赖
composer install

# 不安装开发依赖（生产环境推荐）
composer install --no-dev

# 优化自动加载（生产环境推荐）
composer install --optimize-autoloader

# 不执行脚本（CI/CD 环境推荐）
composer install --no-scripts

# 生产环境完整命令（推荐）
composer install --no-dev --optimize-autoloader --no-interaction --no-progress

# 从特定目录安装
composer install --working-dir=/path/to/project

# 显示详细输出
composer install -vvv

install vs update

这是一个核心区别，很多开发者容易混淆：

# composer install
# - 读取 composer.lock 中的精确版本
# - 如果 lock 文件不存在，则根据 composer.json 解析版本并生成 lock
# - 不会升级已有依赖的版本
# - 用途：日常开发（保持团队一致）和生产部署

# composer update
# - 忽略 composer.lock，重新解析 composer.json 中的版本约束
# - 更新所有依赖到满足约束的最新版本
# - 更新 composer.lock 文件
# - 用途：升级依赖版本

团队协作规则

• 团队成员使用 composer install（不使用 update）
• 只有在需要升级依赖时才使用 composer update
• composer.lock 必须纳入版本控制
• 这样确保所有团队成员和部署环境使用完全相同的依赖版本

update — 更新依赖

# 更新所有依赖到最新版本
composer update

# 仅更新指定的包
composer update monolog/monolog

# 仅更新指定前缀的多个包
composer update guzzlehttp/*

# 更新并删除不再需要的包（Composer 2.2+）
composer update --with-all-dependencies

# 更新但保留 lock 文件中的旧版本信息
composer update --lock

# 仅更新 require-dev 中的依赖
composer update --dev

# 更新到指定版本
composer update guzzlehttp/guzzle:^7.5

# 仅更新最小稳定性以上的版本
composer update --prefer-stable

# 显示详细输出
composer update -vvv

# 常用组合：更新特定包并重新生成自动加载
composer update laravel/framework && composer dump-autoload -o

require — 添加依赖

composer require 用于添加新的依赖包到 composer.json 并立即安装：

# 添加一个包（自动写入 composer.json）
composer require monolog/monolog

# 添加指定版本的包
composer require guzzlehttp/guzzle:^7.5

# 添加开发依赖
composer require --dev phpunit/phpunit

# 添加多个包
composer require psr/log psr/http-message

# 添加带别名的包
composer require vendor/package:1.2.3

# 添加后指定版本约束
composer require phpmailer/phpmailer "^6.0"

# 仅写入 composer.json 不安装（CI/CD 中有用）
composer require --no-update monolog/monolog

# 更新 composer.json 后统一安装
composer install

require 的实际使用场景

# 场景一：开始新项目，安装框架
composer require laravel/framework

# 场景二：添加队列支持
composer require illuminate/queue

# 场景三：添加支付 SDK
composer require yansongda/pay:"~3.0"

# 场景四：添加开发工具
composer require --dev phpstan/phpstan squizlabs/php_codesniffer

# 场景五：修复安全漏洞
composer require "guzzlehttp/guzzle:^7.5"  # 指定安全版本

remove — 移除依赖

# 移除一个生产依赖
composer remove monolog/monolog

# 移除一个开发依赖
composer remove --dev phpunit/phpunit

# 移除多个包
composer remove package-a package-b package-c

# 移除并删除不再需要的依赖
composer remove --unused

remove 命令的行为

composer remove 会：

1. 从 composer.json 中移除该依赖
2. 卸载该包及其文件
3. 如果有其他包依赖它，会提示确认
4. 更新 composer.lock
5. 重新生成自动加载文件

show — 查看依赖信息

# 列出所有已安装的包
composer show

# 查看特定包的详细信息
composer show monolog/monolog

# 输出示例：
# name     : monolog/monolog
# versions : * 2.9.2
# released : 2024-03-15
# descrip. : Sends your logs to files, sockets, inboxes, ...
# type     : library
# license  : MIT
# keywords : log, logging, psr-3
# source   : [git] https://github.com/Seldaek/monolog.git ...
# dist     : [zip] https://api.github.com/repos/Seldaek/monolog/zipball/...
# names    : monolog/monolog
# requires: php ^7.2 || ^8.0, psr/log ^1.0.1 || ^2.0 || ^3.0
# requires (dev): phpunit/phpunit ^8.5.38 || ^9.6 || ^10.0
# suggests: graylog2/gelf-php (Allow sending log messages...)
# ...

# 查看安装了哪些包（仅名称）
composer show --name-only

# 查看特定包的依赖
composer show --tree monolog/monolog

# 查看谁依赖了某个包（反向依赖）
composer why monolog/monolog
# 或
composer depends monolog/monolog

# 查看某个版本是否兼容
composer why-not php 8.2
# 输出： laravel/framework 10.x requires php ^8.1

# 查看所有过期的包
composer outdated

# 以直接可读的格式查看过期包
composer outdated --format=txt

# 以 JSON 格式查看过期包（用于脚本处理）
composer outdated --format=json

search — 搜索包

# 搜索包
composer search monolog

# 搜索并限制结果数量
composer search --only-name laravel

更好的搜索方式

Composer CLI 的搜索功能有限，推荐直接在 Packagist 网站上搜索，可以获得更详细的信息（下载量、描述、GitHub 链接等）。

dump-autoload — 重新生成自动加载

# 重新生成自动加载文件
composer dump-autoload

# 优化自动加载（生成 classmap，性能更好）
composer dump-autoload -o
# 或
composer dump-autoload --optimize

# 无优化重新生成（开发环境推荐）
composer dump-autoload --no-dev

<?php
declare(strict_types=1);

// 什么时候需要运行 dump-autoload：

// 1. 手动修改了 composer.json 的 autoload 配置后
// 2. 新增了类文件但自动加载没有生效
// 3. 删除了类文件
// 4. 切换分支后类文件结构发生变化
// 5. 修改了 namespace 和目录映射

dump-autoload 不安装/卸载包

dump-autoload 仅重新生成 vendor/autoload.php 文件，不会下载或删除任何包。它与 composer install 的区别在于：

• composer install — 安装依赖 + 生成自动加载
• dump-autoload — 仅生成自动加载

create-project — 创建项目

composer create-project 用于从现有模板或包创建新项目，这是初始化框架项目的最常用方式：

# 从 Packagist 创建项目（推荐方式）
composer create-project laravel/laravel my-app

# 指定版本
composer create-project laravel/laravel:^10.0 my-app

# 指定稳定性
composer create-project laravel/laravel my-app --stability=dev

# 从 Git 仓库创建
composer create-project --repository-url=https://repo.example.com myorg/my-app my-app

# 不安装开发依赖
composer create-project laravel/laravel my-app --no-dev

# 跳过交互提示
composer create-project laravel/laravel my-app --no-interaction

常用框架的 create-project 命令

# Laravel
composer create-project laravel/laravel my-app

# Symfony
composer create-project symfony/skeleton my-app

# Slim
composer create-project slim/slim-skeleton my-app

# CodeIgniter
composer create-project codeigniter4/appstarter my-app

# Lumen
composer create-project laravel/lumen my-app

# Yii2
composer create-project yiisoft/yii2-app-basic my-app

# CakePHP
composer create-project cakephp/app my-app

init — 初始化项目

# 交互式创建 composer.json
composer init

# Composer 会询问以下信息：
# Package name (<vendor>/<name>) [myorg/my-app]: myorg/my-app
# Description []: My awesome PHP application
# Author [, n to skip]: Zhang San <zhangsan@example.com>
# Minimum Stability []: stable
# Package Type []: project
# License []: MIT
# Would you like to define your dependencies (require) interactively [yes]?
# Would you like to define your dev dependencies (require-dev) interactively [yes]?

init vs create-project

• composer init — 在已有项目中创建/初始化 composer.json
• composer create-project — 从模板创建全新的项目（包含完整的项目结构）

对于新项目，通常使用 create-project（如创建 Laravel 项目）。对于已有代码需要引入 Composer 管理，使用 init。

全局命令 global

Composer 的全局命令允许你安装全局可用的 CLI 工具：

# 全局安装包
composer global require friendsofphp/php-cs-fixer
composer global require phpstan/phpstan
composer global require beyondcode/expose

# 查看全局安装的包
composer global show

# 全局更新
composer global update

# 全局移除
composer global remove friendsofphp/php-cs-fixer

# 设置全局 Composer Home 目录
# ~/.composer 是默认的全局安装位置
# 修改 COMPOSER_HOME 环境变量可以改变位置
export COMPOSER_HOME=/opt/composer

全局命令的位置

全局安装的包的可执行文件位于 Composer 的 vendor/bin 目录下：

• Linux/macOS: ~/.composer/vendor/bin/ 或 ~/.config/composer/vendor/bin/
• Windows: %APPDATA%\Composer\vendor\bin\

确保此目录在系统 PATH 中，否则全局安装的命令无法直接使用。

# 添加到 PATH（Linux/macOS）
export PATH="$HOME/.composer/vendor/bin:$PATH"

# 永久添加到 PATH
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

其他常用命令

validate — 验证 composer.json

# 验证 composer.json 的语法和有效性
composer validate

# 严格验证（检查仓库是否可访问等）
composer validate --strict

# 输出示例：
# ./composer.json is valid for simple usage with composer but has
# strict errors that make it unable to be published as a package:
# No license specified, it is recommended to do so.

status — 检查修改

# 检查本地修改过的依赖文件
composer status

# 输出示例：
# You have changes in the following vendor packages:
# monolog/monolog
#   M src/Monolog/Handler/StreamHandler.php

# 这在你调试依赖源码时很有用

fund — 捐赠信息

# 查看项目依赖的捐赠信息
composer fund

# 一些包的维护者接受捐赠，Composer 会显示相关信息

licenses — 许可证信息

# 查看所有依赖的许可证信息
composer licenses

# 输出示例：
# Name: guzzlehttp/guzzle
# Version: 7.8.0
# License: MIT

check-platform-reqs — 检查平台要求

# 检查当前 PHP 环境是否满足 composer.json 中声明的要求
composer check-platform-reqs

# 输出示例：
# php    8.3.12    success
# ext-json    1.7.0    success
# ext-pdo    8.3.12    success
# ext-curl    8.3.12    success
# ext-mbstring    *    success

config — 管理配置

# 查看当前配置
composer config --list

# 查看全局配置
composer config -g --list

# 设置全局配置
composer config -g preferred-install dist
composer config -g process-timeout 600

# 设置项目配置
composer config preferred-install dist

# 设置国内镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 查看配置值
composer config preferred-install

depends / prohibits — 依赖分析

# 查看谁依赖了某个包
composer depends psr/log

# 查看某个版本是否被禁止
composer prohibits php:8.4

实战示例：项目初始化脚本

以下是一个完整的项目初始化脚本，综合运用了本节介绍的多个命令：

#!/bin/bash
# project-init.sh — PHP 项目初始化脚本

set -e

PROJECT_NAME=$1

if [ -z "$PROJECT_NAME" ]; then
    echo "用法: ./project-init.sh <项目名>"
    exit 1
fi

echo "=== 创建 Laravel 项目: {$PROJECT_NAME} ==="

# 1. 创建项目
composer create-project laravel/laravel "$PROJECT_NAME" --prefer-dist --no-interaction

cd "$PROJECT_NAME"

# 2. 安装常用开发工具
echo "=== 安装开发工具 ==="
composer require --dev \
    phpunit/phpunit:^10.0 \
    phpstan/phpstan:^1.10 \
    friendsofphp/php-cs-fixer:^3.40 \
    beyondcode/laravel-dump-server:"^1.9"

# 3. 安装常用生产依赖
echo "=== 安装常用依赖 ==="
composer require \
    guzzlehttp/guzzle:^7.5 \
    spatie/laravel-permission \
    intervention/image:^3.0

# 4. 优化自动加载
echo "=== 优化自动加载 ==="
composer dump-autoload -o

# 5. 验证 composer.json
echo "=== 验证配置 ==="
composer validate --strict

# 6. 检查平台要求
echo "=== 检查平台 ==="
composer check-platform-reqs

# 7. 设置文件权限
echo "=== 设置权限 ==="
chmod -R 775 storage bootstrap/cache

# 8. 创建 .env
if [ ! -f .env ]; then
    cp .env.example .env
fi

echo ""
echo "=== 项目创建完成 ==="
echo "目录: $(pwd)"
echo "下一步: cd {$PROJECT_NAME} && php artisan serve"

注意事项

1. 命令执行超时

# 如果 composer install 长时间无响应，可能是网络问题或镜像问题
# 可以增加超时时间：
composer config -g process-timeout 600

# 或临时使用环境变量：
COMPOSER_PROCESS_TIMEOUT=600 composer install

2. 内存不足

# 如果 Composer 遇到内存不足错误
# PHP Fatal error: Allowed memory size of 1610612736 bytes exhausted

# 方式一：使用 -d 参数增加内存
php -d memory_limit=-1 $(which composer) install

# 方式二：设置环境变量
COMPOSER_MEMORY_LIMIT=-1 composer install

# 方式三：修改 php.ini
# memory_limit = -1

3. 网络代理

# 如果使用 HTTP 代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# 如果 Composer 仍然不走代理，可以配置 git 代理
git config --global http.proxy http://proxy.example.com:8080

最佳实践

1. 生产环境部署命令

# 生产环境部署的标准流程
composer install \
    --no-dev \
    --optimize-autoloader \
    --no-interaction \
    --no-progress \
    --prefer-dist \
    --no-scripts

# 或者拆分为更安全的方式
composer install --no-dev --prefer-dist --no-progress
composer dump-autoload --no-dev --optimize

2. CI/CD 中的 Composer 使用

# GitHub Actions 示例
- name: Install Composer dependencies
  run: |
    composer install --no-interaction --no-progress --prefer-dist
    composer dump-autoload --no-dev --optimize

- name: Validate composer.json
  run: composer validate --strict

- name: Check platform requirements
  run: composer check-platform-reqs

3. 使用别名简化命令

# 在 ~/.bashrc 或 ~/.zshrc 中添加别名
alias ci='composer install --no-interaction --prefer-dist'
alias cu='composer update'
alias cr='composer require'
alias creq='composer require'
alias crem='composer remove'
alias cshow='composer show'
alias cdu='composer dump-autoload -o'
alias cout='composer outdated'

# 使用
ci          # composer install
cu          # composer update
cr phpstan  # composer require phpstan

下一节

你已经掌握了 Composer 的核心命令，接下来将学习 PSR-4 自动加载规范，了解 Composer 如何通过命名空间自动加载 PHP 类文件。

参考链接

• Composer 官方文档 — 基本用法
• Composer 官方文档 — 命令行界面
• Composer 官方文档 — 库与项目