Composer自动加载未生效，首要确认根项目是否识别本地包的composer.json；需在根composer.json中通过repositories和require手动声明路径与包名，并确保name字段严格一致。
Composer 自动加载没生效，先确认 autoload 配置是否被识别
本地包（比如 packages/my-utils）的自动加载不生效，最常见原因是 Composer 根项目压根没读到它的 composer.json。Composer 默认只读取项目根目录下的 composer.json，不会递归扫描子目录里的包配置。
你得手动在根项目的 composer.json 中声明这个本地路径：
{
"repositories": [
{
"type": "path",
"url": "./packages/my-utils"
}
],
"require": {
"my-company/my-utils": "*"
}
}
注意：url 是相对路径，且必须指向含有效 composer.json 的目录；require 中的包名要和本地包里 name 字段严格一致（包括大小写）。
- 运行
composer show my-company/my-utils能查到版本，说明路径注册成功 - 如果报
Package my-company/my-utils not found，大概率是name不匹配或repositories没生效 -
composer dump-autoload -v会输出所有被扫描的 autoload 规则，可用来验证本地包的autoload是否被合并进去
本地包用了 psr-4 却找不到类，检查命名空间与目录结构是否对齐
PSR-4 加载失败不是 Composer 的锅，而是 PHP 自动加载器按规则“猜路径”时猜错了。它把命名空间前缀（如 MyCompany\Utils\）替换成目录，再拼上类名剩下的部分（如 StringHelper → StringHelper.php），中间任何一环断掉就失败。
假设你的本地包 composer.json 写着：
{
"autoload": {
"psr-4": {
"MyCompany\Utils\": "src/"
}
}
}
那以下几点必须同时满足：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 类文件必须放在
packages/my-utils/src/StringHelper.php（不能是src/Utils/StringHelper.php） - 文件内必须有
namespace MyCompanyUtils;（反斜杠是转义字符，JSON 里写成\） - 类名必须是
class StringHelper，不能是class UtilsStringHelper - 如果用了子命名空间如
MyCompanyUtilsFileReader，对应路径就得是src/File/Reader.php
用 composer show -s my-company/my-utils 可以快速看到 Composer 解析出的实际 autoload 映射关系，比翻配置更可靠。
改了本地包代码但 require 还是旧类，别忘了 autoload 的缓存机制
Composer 的 autoloader 本身不缓存类文件内容，但它生成的 vendor/autoload.php 是静态映射表——也就是说，只要你没重新生成 autoload 映射，新增的类、改名的类、删掉的类都不会被感知。
- 每次修改本地包的
autoload配置（比如加了个新命名空间）或增删类文件后，必须执行composer dump-autoload - 如果启用了优化模式（
composer install --optimize-autoloader），那ClassLoader会把所有类路径预生成进vendor/composer/autoload_classmap.php，此时仅dump-autoload不够，得加-o参数强制重建 - 开发中建议禁用 classmap 优化：
composer dump-autoload --no-optimize，避免频繁改代码还要等 classmap 重扫
想实时看类是从哪个路径加载的，用 ClassLoader::findFile() 手动查
当 new MyCompanyUtilsStringHelper 报错 Class not found，与其反复猜路径，不如直接问 autoloader 它“想找谁、打算去哪找”：
$loader = require __DIR__ . '/vendor/autoload.php';
var_dump($loader->findFile('MyCompany\Utils\StringHelper'));
返回 false 表示完全没匹配到；返回字符串路径说明找到了，但可能因语法错误或 PHP 版本不兼容导致实际加载失败。
这个方法绕过了 Composer 的命令行工具链，直击底层 ClassLoader 实例，适合嵌入调试脚本或 PHPUnit 测试中快速定位 autoload 断点。
真正麻烦的往往不是配置写错，而是多个本地包之间命名空间冲突、PSR-4 前缀重叠、或者根项目和子包都定义了同名前缀却指向不同目录——这种问题 dump-autoload -v 的输出里会有提示，但默认被刷屏淹没，得盯着看“Warning: Ambiguous class resolution”那一行。
