PSR-4映射需满足：autoload.psr-4为对象，命名空间以“\”结尾，路径为相对路径；类文件路径必须严格匹配命名空间层级，大小写敏感，且修改后须执行composer dump-autoload。

composer.json 里怎么写 psr-4 映射才生效

必须确保 autoload 下的 psr-4 是一个对象（不是数组），键是命名空间前缀（含结尾反斜杠），值是相对于 composer.json 所在目录的源码路径（支持多个）：

{
    "autoload": {
        "psr-4": {
            "App\": "src/",
            "Tests\": "tests/"
        }
    }
}

注意两点：一是命名空间末尾的 \ 不能省，否则 Composer 会当作完全匹配而非前缀匹配；二是路径必须是相对路径，且不以 / 开头，否则运行 composer dump-autoload 会静默失败或报错 Invalid path。

为什么类文件没被自动加载？常见映射错误

最常踩的坑是路径和命名空间对不上。PSR-4 要求类文件路径必须严格反映命名空间层级：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• App\Http\Controller\HomeController → 必须位于 src/Http/Controller/HomeController.php
• 如果实际放在 src/controllers/HomeController.php（小写 controllers），即使映射写了 "App\": "src/"，也会加载失败
• 文件名大小写敏感：Linux/macOS 下 homecontroller.php ≠ HomeController.php，类名与文件名必须完全一致
• 命名空间声明（namespace AppHttpController;）必须和 composer.json 中的前缀拼接后完全匹配

composer dump-autoload 不生效？检查这些点

修改 composer.json 后必须手动刷新自动加载规则，但以下情况会导致刷新无效：

• 没执行 composer dump-autoload，只改了 JSON 就直接跑代码（Composer 不监听文件变更）
• 执行了命令但当前目录不是 composer.json 所在根目录（会读错配置）
• 项目里存在 vendor/autoload.php，但你 include 的是旧版本或别的路径（务必用 require __DIR__.'/vendor/autoload.php';）
• 有其他 autoload 配置（如 files 或 classmap）干扰了 PSR-4 解析顺序（优先级：files > classmap > psr-4）

想给目录起别名？PSR-4 本身不支持“别名”，但可以曲线实现

PSR-4 规范不提供类似 “把 src/ 映射成 MyLib\” 的别名机制——它只认命名空间前缀到路径的单向映射。如果你需要逻辑分组或隐藏真实路径，可行做法只有：

• 在 composer.json 中多加一条映射："MyLib\": "src/"，然后所有类都声明 namespace MyLibXxx;
• 用 repositories + path 类型引入本地包，再通过 require 安装，这样它的 autoload 由子包自己定义，主项目只管引用命名空间
• 避免用 symlink 或重命名目录来“伪装”别名，Composer 不解析符号链接路径层级，会导致类找不到

真正容易被忽略的是：PSR-4 映射一旦写死，就绑定了命名空间结构；重构时若只改目录不动命名空间，或只改命名空间不动文件位置，都会立刻中断自动加载。