symfony bundle 类必须继承 symfony\component\httpkernel\bundle\bundle，命名须以bundle结尾且文件名严格匹配，类需位于psr-4声明路径下，composer.json须设"type": "symfony-bundle"并正确定义autoload，build()方法是注册extension的唯一入口，配置须经configuration+treebuilder驱动。
Bundle 类必须继承 Bundle 且命名规范不能错
Symfony Bundle 的核心是一个 PHP 类，它必须直接继承 Bundle（来自 Symfony\Component\HttpKernel\Bundle\Bundle），否则容器无法识别。很多人写完类发现 bin/console list 不显示命令、服务不加载，第一反应是配置问题，其实常卡在这一行：class MyBundle extends Bundle 漏了 extends Bundle，或用了错误的命名空间（比如写成 use Symfony\Bundle\FrameworkBundle\Bundle —— 这个类不存在，正确路径是 Symfony\Component\HttpKernel\Bundle\Bundle）。
Bundle 类名必须以 Bundle 结尾，且文件名要严格匹配（如 MyBundle.php），否则自动注册失败。Composer 自动发现机制依赖 PSR-4 + 类名后缀双重校验。
- Bundle 类必须放在
src/下（或你自定义的 autoload 路径中），且该路径需在composer.json的"autoload": {"psr-4": {...}}中声明 - 不要把 Bundle 类放进
src/Bundle/子目录——虽然技术上可行，但会破坏 Symfony 的默认扫描逻辑，导致bin/console debug:bundle找不到 - Bundle 类构造函数里不要做任何初始化操作（如读配置、连数据库），它只负责“声明身份”，实际逻辑应交给扩展点（如
build()、getConfigTreeBuilder()）
composer.json 的 type 和 autoload 是复用前提
想让 Bundle 被其他项目通过 Composer 安装并自动启用，composer.json 必须明确声明 "type": "symfony-bundle"。这不是可选标签，而是 Symfony Flex 和内核 Bundle 自动注册的触发条件。没有它，即使包能安装，Kernel::registerBundles() 也不会自动包含你的 Bundle。
autoload 配置更要小心：PSR-4 映射必须覆盖 Bundle 类本身（如 "MyCompany\MyBundle\": "src/"），同时确保所有依赖类（如命令、监听器、配置类）都在同一命名空间下可被加载。常见错误是把 src/ 映射到 "MyBundle\": "src/"，但 Bundle 类实际命名空间是 MyCompany\MyBundle，结果自动加载失败。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 发布到 Packagist 前，用
composer validate检查composer.json格式和字段合法性 - 本地测试时，可用
composer config repositories.mybundle path ./my-bundle+composer require mycompany/my-bundle:dev-main模拟真实安装流程 - 如果 Bundle 提供 Twig 扩展、Doctrine 类型等，需额外在
composer.json中声明"extra"字段（如"symfony-app-dir"或"symfony-web-dir"），但现代 Symfony 5.4+ 多数已不再需要
Bundle 的 build() 方法不是可选钩子，而是扩展容器的唯一入口
很多开发者以为 Bundle 只要存在就能注册服务，其实不然：build(ContainerBuilder $container) 是你向 DependencyInjection 容器注入扩展逻辑的唯一正统方式。漏掉这个方法，或在里面忘记调用 $container->addExtension(...)，会导致配置不生效、服务未注册、参数未解析——哪怕你的 DependencyInjection/MyExtension.php 写得再完整也没用。
注意 build() 里不能直接调用 $container->setParameter() 或 $container->register()，这些操作必须委托给 Extension 类完成。Bundle 本身只负责“告诉容器：我有个 Extension，请运行它”。
- Extension 类必须实现
ExtensionInterface，通常继承Extension（Symfony\Component\DependencyInjection\Extension\Extension） - Extension 类名必须与 Bundle 类名对应（如
MyBundle→MyExtension），且放在DependencyInjection/目录下，否则build()中的$container->registerExtension(new MyExtension())会因类未加载而报Class not found - 别在
build()里做耗时操作（如文件扫描、远程请求），它在每次容器编译时都会执行，影响开发体验和缓存命中率
Bundle 配置必须走 Configuration + TreeBuilder，硬编码配置等于放弃兼容性
如果你在 build() 或 load() 里直接写死参数，比如 $container->setParameter('my_bundle.api_key', 'xxx')，那这个 Bundle 就没法被其他项目安全复用——用户完全无法覆盖、无法禁用、无法条件化配置。真正的配置驱动必须经过 Configuration 类和 TreeBuilder 构建验证树。
常见坑是：写了 Configuration 类，但在 MyExtension::load() 里没调用 $config = $this->processConfiguration($configuration, $configs)；或者 TreeBuilder 返回的是旧版 getRootNode()（Symfony 4.2+ 已废弃），导致配置解析失败却无提示。
-
Configuration类必须返回一个TreeBuilder实例，根节点名必须与 Bundle 名小写一致（如my_bundle对应MyBundle） - 在
MyExtension::load()中，必须用$this->processConfiguration()解析传入的$configs，而不是直接遍历或取值 - 如果 Bundle 支持多环境配置（如 dev/prod 分离行为），应在
Configuration中用$treeBuilder->getRootNode()->children()->arrayNode('environments')->...显式建模，而非靠判断%kernel.environment%硬编码分支
bin/console debug:container --parameter=my_bundle.* 和 bin/console debug:config my_bundle，眼见为实。
