Composer PHP依赖管理教程_Composer安装PHP扩展包方法【基础篇】

写PHP依赖管理，记住一条铁律：别碰 composer update

直接给结论：安装 PHP 扩展包，老老实实用 composer require。千万别随手敲 composer update，否则很可能连带升级其他依赖，线上行为当场翻车。

为什么必须用 composer require 而不是 composer update

composer require 其实就干三件事：写入 composer.json、把包下载到 vendor/、更新 composer.lock。它不会重新计算整个依赖图，也不动那些已经锁定的版本，安全可控。

但 composer update（尤其是不带任何参数）会强制重新解析所有依赖。哪怕你只想加一个 monolog/monolog，它也可能顺手把 lara vel/framework 从 10.42 升到 10.43——别小看这个小版本号，里面可能改了队列重试逻辑或中间件执行顺序，线上立刻抽风。

最佳实践很简单：

• 想加新功能 → 用 composer require vendor/name
• 上线部署 → 只跑 composer install（靠 composer.lock 精确还原）
• 只想升级某一个包 → 明确指定 composer update vendor/name，千万别裸跑 update

composer require 执行前必须确认的三件事

明明没报错，但包就是没装上？大概率卡在这三个地方：

• 当前路径是项目根目录吗？ 运行 ls -la | grep composer.json（Linux/macOS）或 dir composer.json（Windows），确认能看到 composer.json 和 artisan（Lara vel）、public/（ThinkPHP）这些标志性文件。
• Composer 本身能工作吗？ composer --version 得返回有效版本号；如果提示 "command not found"，说明 PATH 没配对，需要重装或手动加路径。
• PHP CLI 版本和关键扩展都就位了吗？ 至少 PHP ≥7.2.5，同时确认 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。别慌，大概率是下面这几个原因：

• Lara vel 8 及更早：必须手动在 config/app.php 的 'providers' 数组加 Lara vel\Socialite\SocialiteServiceProvider::class，并在 'aliases' 加 'Socialite' => ...。少这一步，框架根本认不出它。
• Lara vel 9+：默认启用 auto-discovery，但如果你在 composer.json 里写了 "dont-discover": ["*"]，那就等于全局关闭了自动注册——删掉这行，或者改成 ["lara vel/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 + Lara vel 10，你的 Lara vel 9 项目硬装必然失败。正确做法是查 Packagist 页面的 versions 标签页，确认真实支持范围——别只看 GitHub 上的 "Latest release"。

最后提醒一个容易被忽视的安全问题：vendor/ 目录如果放在 Web 可访问路径下（比如和 index.php 同级），攻击者可以直接下载 vendor/composer/installed.json，暴露你项目里所有依赖的版本信息。务必把 Web 服务器的 root 指向 public/，而不是项目根目录。