Bundle不是必须的，90%新项目不该从写Bundle开始；真要发Packagist，核心是合规composer.json（含"type": "symfony-bundle"、PSR-4 autoload映射到src/、明确symfony依赖版本）和正确命名（vendor-name/package-name-bundle，Bundle类名以Bundle结尾且位于src/根目录）。
直接说结论：Bundle 不是必须的，90% 的新项目不该从写 Bundle 开始；真要发到 Packagist，核心是 Composer 包规范 + 正确的 composer.json + 自动加载配置，不是 Symfony 特有流程。
Bundle 的命名和目录结构怎么才不踩坑
Symfony Bundle 本质是个 PHP 包，但需遵守命名约定才能被自动识别。Bundle 类名必须以 Bundle 结尾，且命名空间需匹配 PSR-4 自动加载路径。
- 推荐命名格式：
vendor-name/package-name-bundle（如acme/demo-bundle），Bundle 类名为DemoBundle - Bundle 类必须放在
src/根下，且文件路径要与命名空间严格一致：src/DemoBundle.php→namespace AcmeDemoBundle; - 别把 Bundle 类塞进
src/Bundle/或src/MyApp/Bundle/—— Symfony 的Kernel::registerBundles()只扫描顶层命名空间，深层嵌套会导致Class "AcmeBundleDemoBundleDemoBundle" not found - Bundle 类必须实现
BundleInterface（继承Bundle基类最省事）
composer.json 怎么写才能被 Packagist 正确收录
Packagist 不关心你是不是 Symfony Bundle，只认 composer.json 里的 type 和自动加载配置。漏掉任一关键字段，就无法被发现或安装失败。
-
"type": "symfony-bundle"是可选但强烈建议加上的字段，能让 Packagist 分类更准，也方便用户搜索 -
"autoload"必须用 PSR-4，且映射到src/："autoload": {"psr-4": {"Acme\DemoBundle\": "src/"}} -
"require"里明确声明最低兼容的 Symfony 版本，例如"symfony/framework-bundle": "^6.4 || ^7.0"；别写"^5.4 || ^6.0"这种跨大版本的宽松约束，容易引发ClassNotFoundException（比如AbstractController在 6.0+ 才引入） - 加
"license"字段（哪怕只是"MIT"），否则 Packagist 会拒绝收录
如何让 Bundle 被 Symfony 应用自动启用
Symfony 6.2+ 默认启用 Flex，但自动启用只对满足特定条件的包生效。你的 Bundle 不会“装上就用”，必须满足两个硬性条件：
- 包名含
-bundle后缀（acme/demo-bundle✅，acme/demo❌） -
composer.json中包含"extra": {"symfony": {"allow-contrib": false}}或类似 Flex 元数据（其实只要包名合规，Flex 通常能猜出它是 Bundle） - 如果想手动注册（比如测试阶段），在
config/bundles.php里加一行：AcmeDemoBundleDemoBundle::class => ['all' => true], - 别在 Bundle 类的
build()方法里调用$container->loadFromExtension()却忘了定义对应配置类 —— 这会导致There is no extension able to load the configuration for "demo"
发布前必须验证的三件事
很多 Bundle 卡在 Packagist 页面显示“no releases”，其实是本地没打 Git tag 或 Composer 配置未同步。
- 确保 Git 仓库公开可访问（Packagist 只抓 GitHub/GitLab/Bitbucket），且主分支为
main或master - 本地执行
composer validate—— 它会检查composer.json语法、必填字段、autoload 路径是否存在等，比人工检查可靠得多 - 打一个语义化版本 tag（如
v1.0.0），然后去 Packagist 点击 “Submit Package”，粘贴仓库 URL；它不会自动监听新 tag，首次提交后，后续新版本需手动点击 “Update” 或配置 webhook
真正麻烦的从来不是“怎么发”，而是“发出去之后别人能不能装、装了能不能跑”。Bundle 的复用性取决于配置是否收敛、服务是否可选、依赖是否最小化——这些细节比注册流程重要十倍。
