前言Symfony 里「创建一个页面」这件事涉及三个必须同时对上的部分路由URL 长什么样、由谁来处理、控制器取出数据、决定返回什么、模板把数据渲染成响应体。三者的连接点都是字符串名字任何一处写错症状都是 404 或者「模板找不到」而且报错信息往往不会直接告诉你是哪一环出了问题。初学者最容易踩的一个版本坑是注解annotation与属性attribute的区别。网上大量教程写的是use Symfony\Component\Routing\Annotation\Route;而从 Symfony 6.4 开始官方推荐use Symfony\Component\Routing\Attribute\Route;到 Symfony 7.0 后者成为唯一选择。照着老教程敲代码第一个use语句就报「类不存在」。还有一个前置事实要说清楚Symfony 的 PHP 版本要求随大版本抬升——6.0 起要求 PHP 8.0.2 以上6.1 起要求 8.17.0 起要求 8.2。具体请以官方文档的 requirements 一节为准安装前先对一下自己的 PHP 版本。本文按「安装 → 路由与控制器 → 模板 → 验证」的顺序走一遍完整流程示例以 Symfony 6.4 / 7.x 为基准。需要说明的是本机没有 PHP 运行时也没有 Composer下面的代码没有实际安装运行验证命令与 API 均按官方文档整理请在你的环境里执行确认。一、安装与目录结构用 Composer 创建项目骨架skeleton是最小安装按需再加功能包# 创建最小骨架项目版本约束可按需调整composer create-project symfony/skeleton:7.0.* my_appcd my_app# 需要模板引擎时装 twig会一并装上 twig-bundlecomposer require twig# 需要数据库与 ORM 时装 orm-packcomposer require symfony/orm-pack# 开发期辅助工具make:controller 等生成器从这一个包来composer require --dev symfony/maker-bundle装完之后几个关键目录的职责如下路径职责src/Controller/控制器命名空间固定为App\Controllersrc/Entity/Doctrine 实体类装了 orm-pack 才有src/Repository/Doctrine 仓储类templates/Twig 模板config/routes.yaml路由总入口通常只负责「去哪加载路由」config/packages/各功能包的配置public/index.php唯一入口Web 根目录必须指向public/var/cache/缓存出问题时清它.env/.env.local环境变量APP_ENV决定加载哪套配置.env里有两个变量决定了整个行为APP_ENVdevAPP_DEBUG1dev环境会打开调试工具条和详细错误页prod环境关闭这些。真正的敏感值数据库密码、API 密钥应当写在.env.local里这个文件默认不会进版本库。二、路由与控制器Symfony 现在的主流做法是把路由直接写在控制器的方法上用 PHP 8 的属性attribute语法声明。config/routes.yaml里只需要告诉框架「去扫描控制器目录」# config/routes.yamlcontrollers:resource: ../src/Controller/type: attribute这里的type值在新版本中是attribute更早的版本写的是annotation。如果你从旧项目迁移这一行是必须改的地方之一。接下来是控制器本体?php // 适用于 Symfony 6.4 / 7.x需要 PHP 8.17.x 需要 8.2declare(strict_types1);namespace App\Controller;use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;use Symfony\Component\HttpFoundation\Request;use Symfony\Component\HttpFoundation\Response;use Symfony\Component\Routing\Attribute\Route;// Symfony 6.3 及更早版本应改为// use Symfony\Component\Routing\Annotation\Route;#[Route(/blog, name: app_blog_)]class BlogController extends AbstractController{#[Route(, name: index, methods: [GET])]public function index(): Response{$posts [[id 1, title 第一篇, summary 摘要内容],[id 2, title 第二篇, summary 摘要内容],];// render() 的第一个参数是模板逻辑名相对 templates/ 目录// 第二个参数中的键会作为变量传给模板return $this-render(blog/index.html.twig, [posts $posts,]);}// 路径里的 {page} 用 requirements 约束成纯数字// 这样 /blog/list/abc 会直接 404而不是进到方法里再判#[Route(/list/{page}, name: list, requirements: [page \d])]public function list(int $page): Response{return $this-render(blog/list.html.twig, [page $page,]);}#[Route(/search, name: search, methods: [GET])]public function search(Request $request): Response{// 查询字符串参数从 $request-query 取不要再依赖 $_GET$keyword (string) $request-query-get(q, );return $this-render(blog/search.html.twig, [keyword $keyword,]);}}几个关键点逐一说明。类上的#[Route]是前缀。类级别写#[Route(/blog, name: app_blog_)]方法级别写#[Route(/{page}, name: list)]最终路径是/blog/{page}路由名是app_blog_list。名字拼接规则是「前缀 方法名」中间不加分隔符所以前缀末尾通常留一个下划线。路由名是全局唯一的重名会在编译期直接报错。属性里的参数是 PHP 8 的命名参数。name:、methods:、requirements:、defaults:这些名字是 Symfony 定义的写错拼写不会报「未知参数」而是会静默失效或者报类型错误所以要照着文档抄。requirements是正则约束。[page \d]强制这一段只能是数字/blog/list/abc会直接 404而不是进到方法里再判。它同时也是避免路由互相抢占的手段假如把这条路由的路径写成/{page}那么/blog/search会被它抢先匹配到search()就永远轮不到执行。这就是路由顺序问题的经典形态——路由按声明顺序匹配先声明的先赢所以更具体的静态路由要写在更宽松的动态路由前面。新版本还支持在路径里内联约束的简写形式形如把正则写在花括号里具体语法以官方文档为准。控制器方法的返回值必须是Response对象。render()返回的是Response可以直接返回返回字符串是不行的。要输出 JSON 就用$this-json($data)要跳转就用$this-redirectToRoute(app_blog_index)。Request对象要通过参数注入获取。Symfony 的参数解析器argument resolver会识别参数类型把当前请求对象注进去参数名随意。所以不要再写$_GET、$_POST$request-query-get()和$request-request-get()才是对应写法而且前者只读查询串、后者只读请求体边界清楚。三、模板与 TwigTwig 模板默认放在templates/下render(blog/index.html.twig)里的路径是相对这个目录的。一个典型的继承结构是「基础模板 子模板」{# templates/base.html.twig #}!DOCTYPE htmlhtml langzh-CNheadmeta charsetUTF-8title{% block title %}我的站点{% endblock %}/title/headbodyheadera href{{ path(app_blog_index) }}首页/a/headermain{% block body %}{% endblock %}/main/body/html{# templates/blog/index.html.twig #}{% extends base.html.twig %}{% block title %}文章列表{% endblock %}{% block body %}h1文章列表/h1{% if posts is empty %}p暂无文章/p{% else %}ul{% for post in posts %}lia href{{ path(app_blog_list, {page: post.id}) }}{{ post.title }}/ap{{ post.summary }}/p/li{% endfor %}/ul{% endif %}{% endblock %}有三点值得专门记住。第一Twig 默认开启 HTML 自动转义。{{ post.title }}会自动把、尖括号、引号转成实体所以对付 XSS 的默认姿势是「什么都不用做」。危险的是|raw过滤器它关闭转义这个过滤器只应该用在你自己完全掌控的内容上绝不能用在用户提交的数据上。同理{% autoescape %}标签可以局部改变转义策略改之前要想清楚用途。第二path()函数根据路由名反向生成 URL比手写路径可靠得多。路由改了路径模板不用动。参数用{page: post.id}这种映射形式传。第三render()的第二个参数里的键会直接成为模板变量。变量名必须是合法的 Twig 标识符也就是字母、数字、下划线不能有短横线——键名里带短横线在 Twig 里没法用点号访问只能退化成attribute()函数徒增复杂度。这是从数组直接透传时最容易忽略的约束。四、验证与调试Symfony 提供了一整套命令行检查工具写完页面不用靠猜# 列出全部已注册路由确认路径与名字对不对php bin/console debug:router# 检查某个具体 URL 会命中哪条路由、绑定到哪个控制器php bin/console router:match /blog/3# 清缓存改配置、加路由后如果行为不对先跑这条php bin/console cache:clear# 检查模板语法php bin/console lint:twig templates/# 检查容器配置php bin/console lint:container本地起服务有两种方式。装了 Symfony CLI 的话直接symfony serve没有 CLI 的话用 PHP 内置服务器注意根目录必须指向public/php -S localhost:8000 -t publicdebug:router是最有用的一个。路由冲突、名字拼错、控制器方法没被发现它都能一眼看出来——它会显示每条路由的路径、名字、HTTP 方法、以及对应的控制器::方法。当页面返回 404 时第一步永远是跑它而不是去改模板。除了命令行还有一个开发期利器路由名写错时Twig 在dev环境下会抛出RouteNotFoundException并把「最接近的可用路由名」列出来通常一眼就能发现是拼写问题。这个特性只在APP_ENVdev时生效prod环境下的表现是不同的错误页。常见坑点❌ 照抄旧教程写use Symfony\Component\Routing\Annotation\Route;。✅ Symfony 6.4 起推荐Symfony\Component\Routing\Attribute\Route7.0 起前者已不可用。先确认项目版本再决定用哪个命名空间。❌ 把config/routes.yaml里的type写成annotation。✅ 新版本里这里应当是attribute。写错会导致控制器里的路由完全不被注册所有页面 404。❌ 把动态路由写在静态路由前面例如先声明/{page}再声明/search。✅ 路由按声明顺序匹配先命中的赢/search会被/{page}抢走。具体路由要放在宽泛路由之前。❌ 控制器方法返回字符串或数组。✅ 控制器必须返回Response对象。渲染页面用$this-render()返回 JSON 用$this-json()跳转用$this-redirectToRoute()。❌ 在控制器里读$_GET/$_POST。✅ 通过参数注入拿到Request对象用$request-query-get()读查询串、$request-request-get()读请求体。两者的边界比超全局变量清楚得多。❌ 在 Twig 里对用户提交的内容使用|raw。✅ Twig 默认自动转义 HTML这是默认的 XSS 防护。|raw会关掉它只应用在完全可信的内容上。❌ 把render()的第二个参数里的键名写成带短横线的形式如user-name。✅ Twig 变量名只能是字母、数字、下划线带短横线的键没法用点号访问。键名应当与模板里使用的变量名完全一致。❌ 把 Web 服务器的根目录指向项目根目录而不是public/。✅ 这样会让.env、config/、var/暴露在 URL 下.env里的数据库密码可被直接下载。根目录必须是public/。总结关注点结论PHP 版本要求6.0 起 8.0.26.1 起 8.17.0 起 8.2以官方 requirements 为准路由声明位置控制器方法上的#[Route]属性config/routes.yaml用type: attribute加载属性类命名空间6.4/7.x 用Routing\Attribute\Route更早版本用Routing\Annotation\Route类级属性的作用给类内所有路由加路径前缀和路由名前缀匹配顺序按声明顺序具体路由必须写在宽泛路由之前控制器返回值必须是Response对象用render()/json()/redirectToRoute()请求参数通过参数注入Request用query/request属性包不用超全局变量模板安全Twig 默认自动转义 HTML慎用 排查工具debug:router、router:match、lint:twig、cache:clear创建页面的流程本身很短声明一条路由让它的名字绑定到一个控制器方法方法里准备数据并指定模板模板继承基础布局输出内容。真正花时间的从来不是「怎么建」而是「为什么 404」——而debug:router能回答其中九成的问题。养成「改完路由先跑一遍 debug:router」的习惯比背下所有属性参数都管用。