Composer不按composer.json中psr-4数组书写顺序决定优先级，而是按最长前缀原则匹配，且vendor映射顺序固化于autoload_psr4.php；重叠前缀无效，重复路径在Composer 2.2+被禁用，prependPsr4()是唯一可靠覆盖方式。
为什么不能在composer.json里调换PSR-4加载顺序
Composer不解析composer.json中autoload.psr-4数组的书写顺序来决定优先级。它把所有项目级PSR-4映射统一注册为一个加载器，而vendor包的PSR-4映射则按依赖拓扑排序固化进vendor/composer/autoload_psr4.php——这个文件里的数组顺序就是运行时实际顺序，但你改composer.json后不dump-autoload，它根本不会更新。
常见误操作包括：
- 在
autoload.psr-4里写两个重叠前缀（如"App\": "src/"和"App\Helper\": "vendor/pkg/src/Helper/"），以为后者会“覆盖”前者——其实不会，因为PSR-4匹配是按最长前缀原则，不是按配置顺序 - 给同一命名空间配两个路径（如
"App\": ["src/", "legacy/"]），这在Composer 2.2+已被禁用，会直接报错 - 指望
prepend: true能影响autoload（该字段只对repositories生效，对autoload无效）
如何让自定义类路径真正优先于vendor
唯一可靠方式是拿到ClassLoader实例，在运行时用prependPsr4()插入更高优先级规则。它会把新映射插到PSR-4查找链最前面，比所有已注册的PSR-4规则都早匹配。
实操要点：
- 必须在
require 'vendor/autoload.php'之后立即操作，否则$loader不是当前生效的实例 - 命名空间末尾必须带反斜杠：
'MyOverride\'，不能写成'MyOverride' - 物理路径必须真实存在、PHP可读，且严格符合PSR-4：类
MyOverrideUserService对应/path/to/override/UserService.php - 若原vendor包也声明了
MyOverride\，你的prependPsr4()会完全屏蔽它，无需卸载原始规则
示例：
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
$loader = require __DIR__ . '/vendor/autoload.php';
$loader->prependPsr4('MyOverride\', __DIR__ . '/overrides/');
$loader->prependPsr4('Legacy\', __DIR__ . '/lib/legacy/');
files加载项为什么总在最前，又为何容易崩
autoload.files被硬编码在vendor/autoload.php顶部执行，目的是提前定义函数/常量。但它不参与类加载流程，只是无条件require——这就带来两个风险：
- 重复
require同名函数文件，直接触发Fatal error: Cannot redeclare function - 在
files里require一个类文件，而该项目又用PSR-4加载同名类，会导致“Class already declared”错误 -
files数组顺序即执行顺序，Composer不做去重或内容校验，冲突源就在composer show -v末尾列出的路径里
安全做法：
- 只放真正需要全局可用的函数定义，且每份
functions.php开头加if (!function_exists('xxx')) {保护 - 避免在
files中require类文件；类应走PSR-4或classmap - 排查冲突时，用
grep -n "function xxx" vendor/*/*/functions.php快速定位重复定义点
离线环境下的autoload失效怎么快速验证
离线时Class not found往往不是文件缺失，而是autoload映射没更新。关键验证点有三个：
- 检查
vendor/composer/autoload_static.php文件修改时间是否晚于composer.json变更时间；若不是，说明dump-autoload没生效 - 运行
composer dump-autoload --optimize（别加--classmap-authoritative，它会删掉PSR-4回退逻辑，离线时更易失败） - 确认opcache是否缓存了旧的autoload_static，临时加
opcache.validate_timestamps=1到php.ini，或调用opcache_reset() - 如果用了
classmap，运行composer dump-autoload -o后，检查vendor/composer/autoload_classmap.php里是否有目标类的映射项
最容易被忽略的是：你以为require 'vendor/autoload.php'成功了，其实它只是加载了空壳——真正的映射表可能因离线跳过生成步骤而为空。此时new任何类都会Class not found，连错误堆栈都看不到autoload环节。
