必须声明"type": "symfony-bundle"，否则无法被Symfony Flex自动启用；PSR-4 autoload须精确匹配Bundle类完整命名空间，如"MyCompanyMyBundle": "src/"，并用path repository和composer validate本地验证。
composer.json 必须声明 "type": "symfony-bundle"
不加这行，你的包就算发布到 Packagist，也无法被 Symfony Flex 自动启用。Flex 会扫描 type 字段，只有值为 "symfony-bundle" 的包才会触发 recipe 安装和 Kernel::registerBundles() 的自动注册逻辑。常见错误是只写 "type": "library" 或干脆省略——结果别人 composer require myvendor/mybundle 后，Bundle 类根本没加载，php bin/console list 里也看不到你的命令。
PSR-4 autoload 映射必须覆盖 Bundle 类本身
假设你的 Bundle 类是 MyCompanyMyBundleMyBundle，那 composer.json 中的 autoload 配置必须让这个类能被自动加载：
- ✅ 正确：
"MyCompany\MyBundle\": "src/"（Bundle 类在src/MyBundle.php，命名空间匹配） - ❌ 错误：
"MyBundle\": "src/"（命名空间前缀少了MyCompany\，自动加载失败） - ❌ 错误：
"MyCompany\MyBundle\": "src/Bundle/"（Bundle 类实际在src/MyBundle.php，路径对不上）
验证方式：在测试项目中 composer require mycompany/mybundle:dev-main 后，运行 php bin/console debug:container --types，看是否能列出你的服务；如果报 Class not found，八成是 autoload 没映射对。
本地开发时用 path repository 模拟真实安装
别等发版才测试，开发阶段就该用 Composer 的本地仓库机制，确保行为和 Packagist 一致：
- 在主项目根目录执行：
composer config repositories.mybundle path ./my-bundle - 再执行：
composer require mycompany/mybundle:dev-main - 这样会软链接
my-bundle目录进vendor/，修改源码立刻生效，且 Flex recipe 也会正常触发
注意：dev-main 要和你 bundle 仓库的默认分支名一致；如果用 main 分支但 composer.json 里写的是 "version": "1.0.0"，Composer 会拒绝安装，因为 dev-main 和稳定版本冲突。建议开发期统一用 dev-main，发版时打 tag 并更新 version 字段。
发布前必须跑 composer validate 并检查 Flex 兼容性
composer validate 不只是校验 JSON 格式，它还会检查 type、autoload、require 等字段是否合法。更关键的是，它能提前发现 Flex recipe 冲突点：
- 如果 bundle 依赖
symfony/framework-bundle，但没声明"symfony/framework-bundle": "^6.4 || ^7.0"这种兼容多主版本的约束，composer validate会警告“minimum-stability mismatch” - 如果 recipe 文件（如
config/packages/mybundle.yaml）引用了不存在的参数（比如%env(MYBUNDLE_API_KEY)%但没在.env或config/services.yaml中定义），cache:clear会失败，但validate不报——得靠本地集成测试
最容易被忽略的是 recipe 中的 copy-from-package 路径：Flex 默认从 bundle 的 Resources/config/ 复制文件，但 Symfony 6+ 推荐用 config/ 目录。如果你把配置文件放错位置，recipe 安装后就是空的。
