企业官网建设流程全解析

前言

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.1，7.0 起要求 8.2。具体请以官方文档的 requirements 一节为准，安装前先对一下自己的 PHP 版本。

本文按「安装 → 路由与控制器 → 模板 → 验证」的顺序走一遍完整流程，示例以 Symfony 6.4 / 7.x 为基准。需要说明的是：本机没有 PHP 运行时也没有 Composer，下面的代码没有实际安装运行验证，命令与 API 均按官方文档整理，请在你的环境里执行确认。

一、安装与目录结构

用 Composer 创建项目，骨架（skeleton）是最小安装，按需再加功能包：

# 创建最小骨架项目（版本约束可按需调整）
composer create-project symfony/skeleton:"7.0.*" my_app

cd my_app

# 需要模板引擎时装 twig（会一并装上 twig-bundle）
composer require twig

# 需要数据库与 ORM 时装 orm-pack
composer require symfony/orm-pack

# 开发期辅助工具：make:controller 等生成器从这一个包来
composer require --dev symfony/maker-bundle

装完之后，几个关键目录的职责如下：

.env里有两个变量决定了整个行为：

APP_ENV=dev
APP_DEBUG=1

dev环境会打开调试工具条和详细错误页，prod环境关闭这些。真正的敏感值（数据库密码、API 密钥）应当写在.env.local里，这个文件默认不会进版本库。

二、路由与控制器

Symfony 现在的主流做法是把路由直接写在控制器的方法上，用 PHP 8 的属性（attribute）语法声明。config/routes.yaml里只需要告诉框架「去扫描控制器目录」：

# config/routes.yaml
controllers:
resource: ../src/Controller/
type: attribute

这里的type值在新版本中是attribute；更早的版本写的是annotation。如果你从旧项目迁移，这一行是必须改的地方之一。

接下来是控制器本体：

<?php // 适用于 Symfony 6.4 / 7.x（需要 PHP 8.1+，7.x 需要 8.2+）
declare(strict_types=1);

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()才是对应写法，而且前者只读查询串、后者只读请求体，边界清楚。

三、模板与 Twig

Twig 模板默认放在templates/下，render('blog/index.html.twig')里的路径是相对这个目录的。一个典型的继承结构是「基础模板 + 子模板」：

{# templates/base.html.twig #}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>{% block title %}我的站点{% endblock %}</title>
</head>
<body>
<header>
<a href="{{ path('app_blog_index') }}">首页</a>
</header>

<main>
{% 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 %}
<li>
<a href="{{ path('app_blog_list', {page: post.id}) }}">
{{ post.title }}
</a>
<p>{{ 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 public

debug:router是最有用的一个。路由冲突、名字拼错、控制器方法没被发现，它都能一眼看出来——它会显示每条路由的路径、名字、HTTP 方法、以及对应的控制器::方法。当页面返回 404 时，第一步永远是跑它，而不是去改模板。

除了命令行，还有一个开发期利器：路由名写错时，Twig 在dev环境下会抛出RouteNotFoundException，并把「最接近的可用路由名」列出来，通常一眼就能发现是拼写问题。这个特性只在APP_ENV=dev时生效，prod环境下的表现是不同的错误页。

常见坑点

1. 
   
2. ❌ 照抄旧教程写use Symfony\Component\Routing\Annotation\Route;。
3. 
   

✅ Symfony 6.4 起推荐Symfony\Component\Routing\Attribute\Route，7.0 起前者已不可用。先确认项目版本再决定用哪个命名空间。

1. 
   
2. ❌ 把config/routes.yaml里的type写成annotation。
3. 
   

✅ 新版本里这里应当是attribute。写错会导致控制器里的路由完全不被注册，所有页面 404。

1. 
   
2. ❌ 把动态路由写在静态路由前面，例如先声明/{page}再声明/search。
3. 
   

✅ 路由按声明顺序匹配，先命中的赢，/search会被/{page}抢走。具体路由要放在宽泛路由之前。

1. 
   
2. ❌ 控制器方法返回字符串或数组。
3. 
   

✅ 控制器必须返回Response对象。渲染页面用$this->render()，返回 JSON 用$this->json()，跳转用$this->redirectToRoute()。

1. 
   
2. ❌ 在控制器里读$_GET/$_POST。
3. 
   

✅ 通过参数注入拿到Request对象，用$request->query->get()读查询串、$request->request->get()读请求体。两者的边界比超全局变量清楚得多。

1. 
   
2. ❌ 在 Twig 里对用户提交的内容使用|raw。
3. 
   

✅ Twig 默认自动转义 HTML，这是默认的 XSS 防护。|raw会关掉它，只应用在完全可信的内容上。

1. 
   
2. ❌ 把render()的第二个参数里的键名写成带短横线的形式，如'user-name'。
3. 
   

✅ Twig 变量名只能是字母、数字、下划线，带短横线的键没法用点号访问。键名应当与模板里使用的变量名完全一致。

1. 
   
2. ❌ 把 Web 服务器的根目录指向项目根目录而不是public/。
3. 
   

✅ 这样会让.env、config/、var/暴露在 URL 下，.env里的数据库密码可被直接下载。根目录必须是public/。

总结

创建页面的流程本身很短：声明一条路由，让它的名字绑定到一个控制器方法，方法里准备数据并指定模板，模板继承基础布局输出内容。真正花时间的从来不是「怎么建」，而是「为什么 404」——而debug:router能回答其中九成的问题。养成「改完路由先跑一遍 debug:router」的习惯，比背下所有属性参数都管用。