必须用 composer require 安装 PHP 扩展包，因它仅写入 composer.json、下载包到 vendor/、更新 composer.lock，不重解析依赖，安全可控；而 composer update 会强制重算整个依赖图，易连带升级其他包（如 laravel/framework 小版本变更引发队列逻辑异常），导致线上行为突变。
直接用 composer require 安装 PHP 扩展包，别碰 composer update，否则容易连带升级其他依赖，线上行为突变。
为什么必须用 composer require 而不是 composer update
composer require 只做三件事：写入 composer.json、下载包到 vendor/、更新 composer.lock。它不重算整个依赖图，不碰已锁版本，安全可控。
composer update（尤其不带参数）会强制重新解析全部依赖，哪怕你只加一个 monolog/monolog，也可能把 laravel/framework 从 10.42 升到 10.43——这个小版本里可能改了队列重试逻辑或中间件执行顺序，线上立刻出问题。
- 想加新功能 → 用
composer require vendor/name - 上线部署 → 只跑
composer install（靠composer.lock精确还原） - 只想升某一个包 → 明确指定
composer update vendor/name，别裸跑update
composer require 执行前必须确认的三件事
命令没报错但包没装上？大概率卡在这三个点：
立即学习“PHP免费学习笔记（深入）”；
- 当前路径是项目根目录：运行
ls -la | grep composer.json（Linux/macOS）或dir composer.json（Windows），确保能看到composer.json和artisan（Laravel）、public/（ThinkPHP）等标志性文件 -
composer --version能返回有效版本号；若提示 “command not found”，说明 PATH 没配对，需重装或手动加路径 - PHP CLI 版本 ≥7.2.5，且关键扩展已启用：运行
php -v和php -m | grep -E "openssl|json|phar|mbstring"，缺模块时composer require会直接失败，错误里常含Could not parse version constraint
装完类找不到？不是没装上，是没注册或没刷 autoload
composer require 成功 ≠ 开箱即用。常见现象：Class 'Socialite' not found、Facade does not exist、Captcha::create() undefined。
- Laravel 8 及更早：必须手动在
config/app.php的'providers'数组加Laravel\Socialite\SocialiteServiceProvider::class，'aliases'加'Socialite' => ... - Laravel 9+ 默认启用 auto-discovery，但如果你在
composer.json里写了"dont-discover": ["*"]，那就等于全局关掉——删掉这行，或改成["laravel/framework"] - ThinkPHP 6/8 扩展大多依赖服务提供者，检查
config/app.php是否已注册对应Service类，如think\captcha\CaptchaService::class - 无论什么框架，装完都建议补一手
composer dump-autoload -o，尤其加了自定义命名空间或本地开发包时
版本写错、镜像超时、PHP 不匹配——最常卡住的三个实际坑
报 Package not found 或 Your requirements could not be resolved，别急着换源，先看这些：
- 包名拼错：比如
maatwebsite/excel少写maatwebsite/，就搜不到；topthink/think-captcha写成think-captcha同样失败 - 国内直连 packagist.org 基本超时，立刻切阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，再composer clear-cache - PHP 或框架主版本不匹配：例如
maatwebsite/excel:^3.4要求 PHP ≥8.0 + Laravel 10，Laravel 9 项目硬装会失败；查 Packagist 页面的versions标签页确认真实支持范围，别信 GitHub 上“Latest release”
真正麻烦的不是命令怎么敲，而是装完之后没人告诉你：那个 vendor/ 目录如果放在 Web 可访问路径下（比如和 index.php 同级），攻击者可能直接下载 vendor/composer/installed.json 暴露所有依赖版本——Web 服务器的 root 必须指向 public/，不是项目根目录。
