Symfony Bundle 要被正确识别、加载、配置和复用，必须同时满足框架识别（类继承Bundle且命名规范）、自动加载（composer.json声明"type":"symfony-bundle"及精准PSR-4映射）、配置集成（实现Extension并支持配置闭环）三重条件。
Bundle 要能被 Symfony 正确识别、加载、配置和复用，光有类文件远远不够——必须同时满足框架识别、自动加载、配置集成三重条件，缺一不可。
Bundle 类必须继承 Bundle 且命名严格匹配
这是 Symfony 扫描和注册 Bundle 的起点。类名不以 Bundle 结尾、文件名与类名不一致、命名空间路径错位，都会导致 debug:bundle 查不到。
-
AcmeDemoBundle是合法类名；AcmeDemo或AcmeDemoBundleClass都不行 - 文件必须叫
AcmeDemoBundle.php，放在src/Acme/DemoBundle/下（对应命名空间AcmeDemoBundle） - 继承语句必须是
use SymfonyComponentHttpKernelBundleBundle;+class AcmeDemoBundle extends Bundle，不能漏命名空间或写错路径
composer.json 必须声明 "type": "symfony-bundle" 和精准 PSR-4 映射
没有 "type": "symfony-bundle"，Flex 就不会触发自动注册，config/bundles.php 也不会自动生成条目；autoload 错了，连类都加载不了，更别说服务或命令。
- ✅ 正确：
"type": "symfony-bundle"+"autoload": { "psr-4": { "Acme\DemoBundle\": "src/" } } - ❌ 错误：
"type": "library"、"Acme\DemoBundle\": "src/Acme/DemoBundle/"（路径多了一层）、"Acme\": "src/"（前缀太短，覆盖不到） - 验证方式：在测试项目中
composer require acme/demo-bundle:dev-main后，运行php bin/console debug:bundle | grep Acme，有输出才算通过
依赖注入扩展（Extension）要实现配置加载闭环
Bundle 不只是挂载点，更是可配置的功能单元。Extension 类负责把用户配置转成容器服务，没它，你的 Bundle 就没法定制行为。
- 类路径必须是
src/Acme/DemoBundle/DependencyInjection/AcmeDemoExtension.php，命名空间为AcmeDemoBundleDependencyInjection - 必须实现
load()方法处理配置数组，并调用$container->loadFromExtension()或手动注册定义 - 必须实现
getConfiguration()返回一个Configuration实例，否则framework.yaml里写acme_demo:会报“unrecognized option” - 若需支持前置配置（如覆盖其他 Bundle 的参数），还需实现
PrependExtensionInterface
本地开发必须用 path repository 模拟真实安装
直接 git clone 到 vendor/ 或硬链接目录，会绕过 Flex 的 recipe 流程和 autoload 注册逻辑，导致行为和线上不一致——这是最常被忽略的验证环节。
- 在主项目执行：
composer config repositories.acmedemo path ./acme-demo-bundle - 再执行：
composer require acme/demo-bundle:dev-main（注意分支名要和你仓库默认分支一致） - 此时
vendor/acme/demo-bundle是软链接，改源码立刻生效，且flex会正常跑 recipe、生成config/bundles.php条目 - 发版前务必跑
composer validate，它会检查type、autoload、require兼容性，尤其是symfony/framework-bundle的版本约束是否写成"^6.4 || ^7.0"
真正卡住人的往往不是写代码，而是 composer.json 里一行 type 字段漏写，或是 autoload 路径差了一个反斜杠——这些细节不验证到真实 require 环境里，根本暴露不出来。
