PSR-4命名空间配置必须确保composer.json中前缀（如"Acme\Utils\": "src/"）、类文件namespace声明（namespace AcmeUtils;）及目录结构（src/Utils/StringHelper.php）三者逐字符严格一致，缺一则Class not found；修改后必须执行composer dump-autoload生效。
扩展包的命名空间配置必须和 composer.json 中的 psr-4 声明、类文件里的 namespace 声明、目录结构三者逐字符对齐，缺一不可；否则 new 实例时直接抛 Class not found。
psr-4 前缀必须以双反斜杠结尾
比如你要用 AcmeUtilsStringHelper，那 composer.json 里必须写成：
"autoload": {
"psr-4": {
"Acme\Utils\": "src/"
}
}
注意："AcmeUtils" 是错的（单反斜杠在 JSON 里会转义成非法字符）；"AcmeUtils" 或 "Acme\Utils" 也不行——前者末尾没反斜杠，匹配不到子命名空间；后者少一级分隔，Acme\Utils\StringHelper 就不会被识别为 src/StringHelper.php。
- Windows 下编辑 JSON 容易误输单反斜杠，建议用双引号包裹并手动敲
\ - PHPStorm 等 IDE 有时会自动“美化”JSON 并删掉一个反斜杠，保存前务必检查
- 路径值
"src/"必须是相对项目根目录的路径，且该目录真实存在（不能是srс/这种拼写错误）
类文件里的 namespace 必须完全一致
src/StringHelper.php 里第一行必须是：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
namespace AcmeUtils;
不是 acmeutils（大小写敏感），不是 Acme/Utils（斜杠不是反斜杠），也不是 AcmeUtilsStringHelper（多了类名）。
- Linux/macOS 文件系统区分大小写，
src/utils/和src/Utils/是两个不同目录 - 如果用了 IDE 的“自动生成 namespace”功能，确认它输出的是反斜杠而非正斜杠
- 一旦改了
namespace，必须同步更新composer.json里的前缀，反之亦然
本地开发时 vendor/autoload.php 不会自动包含你的包
你在主项目中用 repositories 引入本地路径包（如 "type": "path", "url": "../my-package"），主项目的 autoload 不会继承子包的映射规则。
- 必须确保子包自己的
composer.json有合法psr-4配置（如"Acme\": "src/"） - 主项目执行
composer install后，还得再跑一次composer dump-autoload，否则vendor/composer/autoload_psr4.php里没有你的包的映射 - Windows 下若没管理员权限运行终端，symlink 可能静默 fallback 成 copy，导致实际文件已复制但 autoload 仍查原路径——此时删掉
vendor/myvendor/mypackage再重装更稳妥
下划线类名或 Legacy_ 前缀必须走 classmap
PSR-4 完全不处理下划线，像 Legacy_StringHelper 或 Old_Core_Service 这类命名，哪怕你把它放进 legacy/ 目录，也绝不会被 psr-4 匹配到。
- 正确做法是在子包的
composer.json中加："autoload": { "classmap": ["legacy/", "old/"] } - 然后在子包根目录下运行
composer dump-autoload（不是主项目） - 生成的
vendor/composer/autoload_classmap.php会包含这些类的绝对路径映射，但性能略低，仅适合过渡或遗留代码
最常被忽略的一点：改完任何 autoload 配置后，composer dump-autoload 是硬性步骤，不是可选操作；它不随 install 或 update 自动触发，漏掉就等于没配。
