镜像配置不影响插件加载路径，但会放大已有冲突：换阿里云或腾讯云镜像后插件不生效，本质是新镜像拉取更准确元数据，暴露了本地插件路径注册问题，如composer-plugin-api版本不匹配、主项目psr-4宽泛前缀覆盖插件autoload、classmap路径重叠导致静默覆盖，或离线时autoload_static.php未重建。
镜像配置不影响插件加载路径，但会放大已有冲突
换阿里云或腾讯云镜像后插件突然不生效，不是镜像改了路径逻辑，而是它拉取了更准确的元数据，暴露了你本地已存在的插件路径注册问题。镜像只加速下载、不修改 autoload 行为，但会更快触发 composer-plugin-api 版本校验——比如你装的是 Composer 2.4，而插件 require "composer-plugin-api": "^2.5"，旧镜像缓存可能跳过检查，新镜像则直接拒绝加载。
常见现象：Plugin installation failed 或插件命令（如 phpstan、larastan）完全不响应，composer show --tree 里根本看不到该插件。
- 先运行
composer --version确认当前 Composer 主版本 - 再查它实际提供的插件 API：
composer show composer/composer | grep plugin-api - 对比插件包的
composer.json中"require": {"composer-plugin-api": "..."}是否匹配（注意：^2.5不兼容2.4.x） - 若不匹配，要么升级 Composer（
composer self-update），要么降级插件（找支持2.4的老版本）
插件 autoload 路径被主项目 PSR-4 覆盖
插件类（如 Vendor\Plugin\Installer）报 Class not found，但 vendor/vender/plugin/src/Installer.php 明明存在——大概率是主项目的 composer.json 里写了宽泛 PSR-4 映射，例如 "": "src/" 或 "App\": "src/"，导致 Composer 把插件类名也按这个规则去 src/ 下找，自然扑空。
验证方式：运行 composer dump-autoload -vvv | grep "Vendor\Plugin\"，看输出里是否出现插件自己的 PSR-4 映射；如果没出现，说明插件的 autoload 配置压根没被读取（可能是插件未正确声明 type=composer，或被 repositories 配置绕过了）。
- 检查插件包的
composer.json是否含"type": "composer-plugin"和有效的"autoload": {"psr-4": {...}} - 确认主项目
composer.json的"autoload"段没用""或"App\"这类全局前缀，尤其避免"": "src/"—— 它会让所有未声明命名空间的类都去src/找 - 不要在主项目 autoload 里手动加
"Vendor\Plugin\": "vendor/vendor/plugin/src/"—— Composer 插件的 autoload 应由其自身声明，主项目不该越权接管
classmap 与插件 PSR-4 同名类导致静默覆盖
插件提供了一个 Helper 类，你项目里也有 src/Helper.php，两者都用了 classmap 扫描（比如主项目写了 "classmap": ["src/"]，插件也写了 "classmap": ["src/"]），结果运行时总是加载你项目的 Helper，插件功能异常——这不是报错，而是 classmap 查表时后注册的路径覆盖了前一个。
classmap 不走命名空间，只靠文件名匹配，且无冲突提示。PSR-4 映射则依赖命名空间前缀，更可控。
- 插件应优先用 PSR-4，而非 classmap；若必须用 classmap，确保其路径唯一（如
"classmap": ["lib/"]，而非["src/"]） - 主项目若用了
"classmap": ["src/"]，就别把插件源码目录软链进src/—— 这等于主动制造重复扫描 - 排查方法：删掉
vendor/composer/autoload_classmap.php，执行composer dump-autoload -o，再打开该文件搜Helper，看它指向哪个路径
离线环境插件 autoload 失效的隐藏原因
服务器断网后插件命令失效，Class not found，但 vendor/autoload.php 存在、composer dump-autoload --optimize 也跑过——问题常出在插件的 autoload 静态映射没随主项目一起重建。
Composer 插件的 autoload 规则不是写死在 vendor/autoload.php 里，而是由 vendor/composer/autoload_static.php 动态合并生成。离线时 composer install 可能跳过这步，尤其当插件是通过 path repository 引入时。
- 强制重建：运行
composer dump-autoload --optimize（别加--classmap-authoritative，它会删掉 PSR-4 fallback，离线时更脆） - 验证文件更新时间：
ls -l vendor/composer/autoload_static.php对比composer.json修改时间，不一致说明没生效 - path 类型插件要特别注意：确保其目录下
composer.json的"autoload"字段真实存在且语法正确（JSON 逗号、引号、末尾反斜杠缺一不可）
composer-plugin-api 版本、PSR-4 前缀撞车、classmap 扫描路径重叠这三处。镜像只是让这些底层问题浮出水面更快——别调镜像，先调清楚 autoload 规则谁在注册、谁在覆盖、谁根本没注册。
