Symfony路由配置入门教程，手把手教你写第一个页面

写第一个 Symfony 页面，动作其实很小：注册一条路由，让它指向某个控制器方法，然后浏览器能访问到。真正卡住人的往往不是代码本身，而是路由文件没加载控制器的目录、属性路由的命名空间写错，或者只改了 prod 环境的缓存却忘了清。先确认项目的 Symfony 版本和它当前采用的路由加载方式，再决定把路由写在控制器里还是写在 config/routes.yaml 里，两者选一种，不要混着改同一个路径。

适用场景：在已能启动的 Symfony 项目里新增一个可访问页面，框架版本大致在 5.4 及以上。操作动作：先用 bin/console debug:router 看清现有路由表，再在控制器上用属性路由，或在 config/routes.yaml 中显式声明路径并指向控制器方法。验证方式：路由命令能列出新路径，用 curl 访问返回 200 和预期文本。风险边界：属性路由的命名空间随版本变化，控制器目录若未被路由配置引入则新路由不生效，prod 环境改完需要清缓存。

先确认当前场景和目标

这一步的判断条件是：项目能不能正常启动、路由目前由谁加载、你打算返回纯文本还是渲染模板。三者不清楚，后面写出来的代码大概率跑不通。

查版本：php bin/console --version，或直接看 composer.json 中 symfony/framework-bundle 的约束。Symfony 6 及以上通常默认使用 PHP 属性路由，5.x 项目则常见 YAML 与注解混用。
看路由入口：打开 config/routes.yaml，确认是否有一段落把 src/Controller/ 目录整体导入为 type: attribute（旧项目可能是 annotation）。没有这段，控制器上写什么都不会被注册。
确认入口文件与端口：public/index.php 存在，说明是常规 Web 项目；本地起服务用 symfony serve 或 php -S 127.0.0.1:8000 -t public。
明确本次目标：浏览器访问 /hello/张三 返回一段文本，不接数据库、不渲染 Twig，先把路由链路跑通。

按这个顺序处理

按下面的顺序走，出错时能快速定位是哪一环断的。

先看现状：执行 php bin/console debug:router，会列出当前所有路由名、方法和路径。记下已有的命名前缀风格，新路由名建议沿用同样规则，例如 app_hello。
确认加载方式：若 config/routes.yaml 里已有 controllers 目录的导入段，就走属性路由；否则在 yaml 中补一段，或直接在 yaml 里手写这一条路由。
写控制器方法：下面是属性路由写法，命名空间要按版本替换。Symfony 6/7 用 Symfony\Component\Routing\Attribute\Route，5.2 到 5.4 用 Symfony\Component\Routing\Annotation\Route。

<?php
// src/Controller/HelloController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class HelloController extends AbstractController
{
    #[Route('/hello/{name}', name: 'app_hello', methods: ['GET'])]
    public function hello(string $name = 'world'): Response
    {
        return new Response('Hello ' . htmlspecialchars($name));
    }
}

如果项目走 YAML，控制器里去掉属性注解，路径改在配置文件里声明，其他不变：

# config/routes.yaml
app_hello:
    path: /hello/{name}
    controller: App\Controller\HelloController::hello
    methods: [GET]
    defaults:
        name: world

两段代码里的 /hello/{name}、app_hello、控制器类名与方法名都是可替换项，换成你自己的路径和命名即可。占位符 {name} 默认匹配不含斜杠的片段，需要限制格式时可加 requirements: { name: '[a-zA-Z]+' }。

改完后怎么验证

验证分三层，从路由表到 HTTP 响应逐层确认，出问题时能立刻知道卡在哪一层。

路由层：再执行一次 php bin/console debug:router app_hello，预期输出里能看到路径 /hello/{name}、方法 GET 和对应的控制器方法。查不到说明路由没被加载，回到上一步看 yaml 的导入段。
HTTP 层：curl -i http://127.0.0.1:8000/hello/张三，预期返回 HTTP/1.1 200 和正文 Hello 张三。改成 curl -i -X POST 同一地址，预期是 405，说明 methods 限制生效。
异常层：访问一个不存在的路径如 /nope，预期 404；如果此时返回 500，问题在控制器或依赖注入，不在路由。
环境层：dev 环境改完通常无需手动清缓存，prod 环境需要执行 php bin/console cache:clear --env=prod 再测，否则看到的仍是旧路由。

容易忽略的边界

以下几处最容易在“本地好好的、换个环境就不对”时暴露出来，动手前先对照一遍。

属性路由命名空间与版本绑定。把 6.x 的 Attribute\Route 粘到 5.3 项目里会直接报类不存在，反之旧注解在新版本上也可能被标记为弃用。改之前先确认版本，不确定就用 YAML 写法，兼容范围更宽。
路由缓存与容器编译。改了 config/routes.yaml 或控制器签名后，如果 debug:router 结果没变，先清 var/cache；权限不足导致缓存写不进去时，表现同样是路由不更新，需要确认运行用户对 var/ 目录有写权限。
路径前缀与部署位置。应用挂在子目录（如 /app）下时，路由路径本身不用改，但反向代理或 config/routes.yaml 里的 prefix 会影响最终 URL，别只按本机根路径去判断。
参数类型与安全。占位符传进来的永远是字符串，方法签名写 int $id 时框架会做转换，转换失败通常表现为 404 而非 500，排查时别只盯控制器代码。{name} 这类自由文本在输出前建议转义，避免直接拼进 HTML。
回退建议：如果一时判断不清是路由问题还是控制器问题，可以先临时把路由指向一个只返回固定字符串的闭包或最小方法，确认链路通了再换回真实逻辑；也可以先把新路由注释掉，对比 debug:router 的输出差异来定位。这套做法只用于定位，不作为长期方案保留。