必须严格配置镜像源三要素：键名repo.packagist、type值composer、URL末尾带斜杠，缺一即静默失效；换源后须删除vendor和composer.lock再执行composer install，否则因lock文件哈希不匹配导致下载失败。
镜像源必须配对且格式严格，否则等于没配
配镜像不是输完命令就完事，repo.packagist 键名、composer type 值、URL 末尾斜杠三者缺一不可。写成 repos.packagist（多一个 s）或 https://mirrors.aliyun.com/composer（少斜杠），Composer 会静默 fallback 到官方源，日志里看不到报错，但下载速度原地不动。
验证是否生效，直接运行：composer config -g repo.packagist
输出必须是类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON；如果返回空、null 或仍是 https://packagist.org，说明配置失败。
推荐用阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
换源后必须删 vendor 和 composer.lock 再重装
镜像只加速下载，不改变包内容，但旧 composer.lock 里记录的是 packagist.org 的哈希值，和新镜像返回的元数据不兼容。继续用旧 lock 文件，Composer 会反复尝试校验失败，卡在 TLS 握手或 404。
立即学习“PHP免费学习笔记（深入）”；
正确做法是：
- 进入项目根目录（确认有
composer.json） - 执行
rm -rf vendor composer.lock（Linux/macOS）或rd /s/q vendor && del composer.lock（Windows） - 再跑
composer install或composer require xxx/xxx
别试图保留旧 composer.lock —— 它不是缓存，是锁定文件，换源后它已失效。
ThinkPHP/Laravel 扩展装上了但类找不到？注册没做全
装完 topthink/think-captcha 或 laravel/socialite 后，use think\captcha\Captcha; 或 Socialite::redirect() 报错，不是没装上，是服务提供者没注册或自动发现被关了。
检查这几处：
- Laravel 8 及更早：手动往
config/app.php的'providers'数组加think\captcha\CaptchaService::class或Laravel\Socialite\SocialiteServiceProvider::class - ThinkPHP 6/8：确认
config/app.php中'providers'是否包含对应服务提供者类 - 全局关闭自动发现？检查
composer.json里有没有"dont-discover": ["*"]—— 这行会让所有包都失能，删掉或精确限定范围 - 部分扩展（如
think-queue）需复制配置文件：从vendor/topthink/think-queue/config/queue.php手动拷到项目config/目录下
PHPUnit 或 dev-only 包必须带 --dev 参数
装 phpunit/phpunit 时漏掉 --dev，它会被写进 require 段，导致线上环境也拉取测试工具，CI 构建加了 --no-dev 就直接失败。
正确命令是：composer require --dev phpunit/phpunit:^11.0
版本还得匹配 PHP：
- PHP 8.2+ → 用
^10.5或^11.0 - PHP 8.0–8.1 → 用
^9.6（LTS） - PHP 7.4 → 只能用
^8.5
装完立刻验证：ls -l vendor/bin/phpunit（Linux/macOS）或 dir vendor\phpunit.bat（Windows），有可执行文件才算成功。
最常被忽略的点：换镜像源后不删 composer.lock，以为“命令跑完了”就结束了；还有就是 composer require 装完不查服务提供者注册状态，直接写代码，结果报 Class not found 却回头折腾安装命令。
