Symfony MVC以Controller为调度中心，Model与View解耦协作；目录结构与autoloader、环境配置、缓存强绑定，文件位置、命名空间或缓存未清均会导致Class not found等错误。
Symfony 的 MVC 不是教科书式的线性流程，而是以 Controller 为调度中心、Model（Entity + Repository）与 View（Twig 模板）解耦协作的运行模型。目录结构不是静态摆设，而是和 autoloader、环境配置、缓存机制强绑定的执行契约 —— 文件放错位置、命名空间不匹配、缓存未清，都会直接导致 Class not found 或 ServiceNotFoundException。
Controller 怎么定位？别只看 src/Controller
Symfony 的控制器必须满足两个硬条件：类文件在 src/Controller/ 下，且命名空间为 App\Controller。但真正触发执行的是路由配置（config/routes.yaml 或注解），不是文件路径本身。
- 常见错误现象：
Unable to find controller "App\Controller\BlogController::list"，实际文件存在，但路由里写成了App\Blog\Controller::list—— 命名空间和路由定义必须一致 - 使用场景：开发中常把 API 控制器和 Web 控制器混放，建议用子命名空间隔离，如
App\Controller\Api\PostController→ 对应文件src/Controller/Api/PostController.php - 参数差异：注解路由（
@Route）需启用annotations: true配置；YAML 路由更易维护，但不支持动态参数默认值内联写法 - 性能影响：路由编译后缓存在
var/cache/{env}/srcApp_Kernel{env}DebugContainer.php，改了路由必须清缓存，否则旧规则仍生效
Entity 和 Repository 放哪？别碰 config/doctrine/
Doctrine Entity 不是“数据库表映射文件”，而是带业务逻辑的 PHP 类；Repository 是它的数据访问代理。它们的位置和命名空间直接影响 Doctrine 的自动发现和命令行工具行为。
- 标准路径：
src/Entity/User.php→ 命名空间App\Entity；src/Repository/UserRepository.php→ 命名空间App\Repository - 容易踩的坑：
php bin/console doctrine:make:entity生成的类若手动移到src/Model/，后续doctrine:schema:update会完全忽略它 —— Doctrine 只扫描App\Entity命名空间 - 配置项影响：
doctrine.orm.mappings.App.type: attribute表示用 PHP 8 属性做映射，若降级到 YAML 配置，实体类里就不能有[ORM\Entity] - 性能注意：Repository 方法名如
findByPublishedAtBetween()会被 Doctrine 自动解析为 DQL，但复杂查询建议显式写createQueryBuilder()，避免魔法方法隐式开销
Twig 模板路径为什么总报 404？检查 Resources/views 和 templates
Symfony 6+ 默认模板根目录是 templates/（非旧版的 src/Resources/views），这个变化常被忽略，尤其从老项目升级时。
- 正确路径：
templates/blog/index.html.twig→ 在控制器中 render('blog/index.html.twig') - 常见错误现象：
Unable to find template "base.html.twig"，实际文件在templates/base.html.twig，但控制器写了render('base.html.twig')—— Twig 默认不搜索根模板，必须写全路径或用块继承约定 - 使用场景：重写第三方 Bundle 模板（如
FOSUserBundle）要放在templates/bundles/FOSUserBundle/Security/login.html.twig，路径层级必须严格匹配 Bundle 的原始视图路径 - 兼容性影响：
twig.default_path参数可覆盖默认模板根目录，但不推荐；多环境时，APP_ENV=prod下模板缓存编译为 PHP，路径错误会在首次访问时报致命错误，而非开发时的清晰异常
var/cache 和 var/log 不是“日志缓存文件夹”，是运行时契约的一部分
var/ 目录下每个子目录都对应一个内核参数，硬编码进容器，不能靠文件系统权限或挂载点随意干预。
- 缓存路径由
kernel.cache_dir控制，默认是var/cache/{env}，但可被环境变量SYMFONY_CACHE_DIR覆盖 —— Docker 部署时若只挂载var/cache/prod，却没设该变量，缓存仍会写入默认位置，造成双写或失效 - 日志路径由
monolog.handler.main.path控制，默认是var/log/{env}.log，但轮转策略（如max_files: 10）在config/packages/prod/monolog.yaml中定义，和文件系统无关 - 容易踩的坑：CI/CD 流水线里执行
bin/console cache:clear --no-warmup后直接启动服务，结果首页报错 —— 缺少cache:warmup，容器、路由、Twig 模板都没预编译，首次请求超时 - 部署建议：生产环境清缓存必须用
bin/console cache:clear --env=prod && bin/console cache:warmup --env=prod，不能只删var/cache/prod文件夹
最常被忽略的其实是 composer.json 里的 PSR-4 映射 —— 它不是“让类能被加载”的可选项，而是整个 autoloader 的注册契约。改了命名空间、移动了文件、甚至只是加了个空格，都得立刻跑 composer dump-autoload，否则 Symfony 根本看不见你写的任何新类。
