PSR-4命名空间必须以结尾且不可与项目根命名空间重叠，否则导致类加载失败；需严格分离autoload与autoload-dev，修改composer.json后必须执行composer dump-autoload -o更新缓存。
包开发时命名空间必须带末尾反斜杠，且不能和项目根命名空间重叠——否则用户安装后 Class not found 的第一反应永远是“你包写错了”，其实错在你没守住边界。
为什么包的 PSR-4 命名空间必须以
Composer 解析 composer.json 里的 "MyPackage\": "src/" 是按字符串前缀匹配的。如果写成 "MyPackage"（无反斜杠），JSON 解析后就是字面量 "MyPackage"，导致 MyPackageHttpClient 被截成 HttpClient，最终去拼 src/Http/Client.php——但你的类实际在 src/Http/Client.php 下，路径对不上。
更隐蔽的问题是：不加反斜杠时，MyPackageFoo 也会被错误匹配，而它根本不是你的包。
-
"MyPackage\": "src/"✅：正确声明命名空间前缀，匹配MyPackageHttpClient时只砍掉MyPackage -
"MyPackage": "src/"❌：JSON 解析为纯字符串，匹配逻辑崩坏 -
"MyPackage": "src/"❌：Windows 下易多打一个反斜杠，PHP 字符串解析会出错
包命名空间不能和用户项目共用前缀
假设你开发一个通用日志包，命名为 logger，却用 "App\": "src/" 作为 PSR-4 映射——那用户自己的 Laravel 项目也用 App，Composer 加载时就会混乱：到底是加载用户的 AppHttpControllerHome，还是你包里的 AppLoggerHandler？
立即学习“PHP免费学习笔记（深入）”；
PSR-4 按最长前缀优先，但用户项目通常比你的包更早执行 dump-autoload，结果你的类可能根本进不了自动加载表。
- 包命名空间应唯一、可识别，推荐格式：
VendorNamePackageName（如MonologLogger） - 绝对不要复用常见项目前缀：
App、Core、Http、Models - 若包需提供“开箱即用”的类（如
Logger），应在顶层命名空间下放Logger.php，对应namespace VendorNamePackageName;，而非塞进VendorNamePackageNameUtils
autoload-dev 不是可选项，而是隔离红线
测试类（如 TestsUnitLoggerTest）如果混进主 autoload，用户 composer install --no-dev 后仍会加载它们——不仅浪费内存，还可能因依赖未安装（如 phpunit）导致 Fatal error: Class 'PHPUnitFrameworkTestCase' not found。
更严重的是，某些测试类里写了 class_alias() 或修改了全局状态，会污染用户运行时环境。
- 生产 autoload 只该包含真正对外暴露的类，路径严格限定在
src/或明确公开目录 -
autoload-dev必须单独配置，且路径不能与autoload.psr-4重叠 - CI/CD 中验证命令应含
composer install --no-dev --optimize-autoloader，确保生成的autoload_psr4.php不含测试代码
改完 composer.json 后必须跑 composer dump-autoload -o
很多人本地调试时只改 composer.json 就直接 require 'vendor/autoload.php'，结果报 Class not found。因为 vendor/autoload.php 实际读的是 vendor/composer/autoload_psr4.php 这个缓存文件，不是实时解析 JSON。
不加 -o 也能工作，但每次加载都要动态拼路径、检查文件是否存在；加了之后生成静态映射，跳过所有文件系统调用——尤其在 CI 环境或容器中，IO 慢得明显。
- 开发阶段：改完立即执行
composer dump-autoload -o - 不要依赖 IDE 自动刷新或 Composer 插件“悄悄帮你 reload”——它不会
- Git 提交前确认
vendor/composer/autoload_psr4.php已更新（尤其多人协作时）
最常被忽略的一点：命名空间不是“起个名字就行”，它是 Composer 加载器眼里的一条硬编码路径规则。哪怕只是少了一个反斜杠、多了一个空格，或者大小写错了一处，都会让整个加载链断裂——而且错误信息从不告诉你哪里错了，只说 Class not found。
