拆分 Composer 组件包关键在于 autoload 映射、config 注入点、生命周期兼容性三者对齐主框架；漏掉任一环节会导致类找不到、配置不生效或服务未注册。
直接说结论：拆分 Composer 组件包不是“把代码挪进新目录”就完事，关键在于 autoload 映射、config 注入点、生命周期兼容性这三处是否对齐主框架——尤其当目标是 Hyperf、Laravel 或 Symfony 这类有容器和启动流程的框架时，漏掉任意一项都会导致类找不到、配置不生效或服务未注册。
为什么 vendor/package 里的类死活不被自动加载
常见错误现象是 Class "MyPackageFoo" not found，即使 composer dump-autoload -o 已执行、src/ 目录结构也完全符合 PSR-4。根本原因往往出在两个地方：
-
composer.json中autoload.psr-4的命名空间末尾没加反斜杠，比如写成"MyPackage\":"src/"是对的，但写成"MyPackage":"src/"就会导致MyPackageFoo匹配失败 - 主项目未重新运行
composer install或composer update，仅靠dump-autoload不会更新vendor/composer/autoload_psr4.php中的映射表（该文件由 Composer 安装/更新流程生成） - 组件包被声明为
type: library，但主项目用了 path repository 引入本地包，而路径未设为绝对路径或未启用options.symlink: true，导致符号链接失效，vendor/下实际是拷贝而非链接，autoload 无法穿透
Hyperf 组件包里 ConfigProvider 不生效的典型原因
Hyperf 的组件加载依赖 extra.hyperf.config 字段指向一个实现了 HyperfContractConfigProviderInterface 的类，这个类必须返回特定结构的数组。容易踩的坑包括：
-
composer.json中漏写extra.hyperf.config，或值写错类名（比如少了Hyperf前缀，或拼错ConfigProvider后缀） - ConfigProvider 类中返回的
dependencies键值对里，接口名写成了具体类名（如FooInterface::class => Foo::class写成Foo::class => Foo::class），导致 DI 容器无法绑定 - 组件包的
autoload没覆盖 ConfigProvider 所在路径（例如 ConfigProvider 放在src/，但psr-4映射的是MyPackage\到src/MyPackage/），结果类根本加载不进来
如何让同一个组件包同时适配 Laravel 和 Hyperf
核心思路是「配置分离 + 条件加载」，而不是硬编码框架耦合逻辑。真实可行的做法是：
- 在组件包
composer.json的require中不强制依赖任何框架，只声明 PHP 版本与基础工具（如psr/container） - 将框架专用逻辑拆到独立目录：
src/Laravel/放ServiceProvider，src/Hyperf/放ConfigProvider，各自通过autoload.psr-4显式映射 - 不提供统一入口；由下游框架项目自行选择加载方式：Laravel 项目 require 组件后，在
config/app.php的providers数组里手动添加MyPackageLaravelServiceProvider::class；Hyperf 项目则确保extra.hyperf.config指向MyPackageHyperfConfigProvider - 避免在组件内调用
app()、Container::get()等框架特有函数，所有依赖通过构造注入或接口契约传递
最常被忽略的一点：组件包的 tests/ 目录下如果用了框架专属的测试基类（比如 TestCase 继承自 OrchestraTestbenchTestCase），那这个测试套件本质上已绑定 Laravel，无法代表“通用组件”的可复用性——真正解耦的组件，应能脱离任何框架单独跑通单元测试。
