Symfony Bundle开发的完整流程和规范-php教程-PHP中文网

symfony bundle 要被正确识别、加载、配置和复用，必须同时满足框架识别（类继承bundle且命名规范）、自动加载（composer.json声明"type":"symfony-bundle"及精准psr-4映射）、配置集成（实现extension并支持配置闭环）三重条件。

symfony bundle开发的完整流程和规范

Bundle 要能被 Symfony 正确识别、加载、配置和复用，光有类文件远远不够——必须同时满足框架识别、自动加载、配置集成三重条件，缺一不可。

这是 Symfony 扫描和注册 Bundle 的起点。类名不以 Bundle 结尾、文件名与类名不一致、命名空间路径错位，都会导致 debug:bundle 查不到。

AcmeDemoBundle 是合法类名；AcmeDemo 或 AcmeDemoBundleClass 都不行
文件必须叫 AcmeDemoBundle.php，放在 src/Acme/DemoBundle/ 下（对应命名空间 AcmeDemoBundle）
继承语句必须是 use SymfonyComponentHttpKernelBundleBundle; + class AcmeDemoBundle extends Bundle，不能漏命名空间或写错路径

没有 "type": "symfony-bundle"，Flex 就不会触发自动注册，config/bundles.php 也不会自动生成条目；autoload 错了，连类都加载不了，更别说服务或命令。

Symfony Linux版

Symfony Linux版整理 Symfony CLI 5.17.1 官方下载入口和 Symfony 框架安装配置说明。

下载

✅ 正确："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，有输出才算通过

Bundle 不只是挂载点，更是可配置的功能单元。Extension 类负责把用户配置转成容器服务，没它，你的 Bundle 就没法定制行为。

类路径必须是 src/Acme/DemoBundle/DependencyInjection/AcmeDemoExtension.php，命名空间为 AcmeDemoBundleDependencyInjection
必须实现 load() 方法处理配置数组，并调用 $container->loadFromExtension() 或手动注册定义
必须实现 getConfiguration() 返回一个 Configuration 实例，否则 framework.yaml 里写 acme_demo: 会报“unrecognized option”
若需支持前置配置（如覆盖其他 Bundle 的参数），还需实现 PrependExtensionInterface

直接 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"