要在 Symfony 7.0 中创建专供前后端分离使用的 API 接口，必须跳过 Twig 渲染、禁用 HTML 响应、统一错误结构，并确保 JSON 数据可被 Vue 或 React 安全消费——任何一步遗漏都会导致前端拿到 HTML 字符串而非解析后的对象。
禁用 Twig 渲染并强制返回 JSON
打开 config/packages/framework.yaml，确认以下配置已启用：
framework:
json_request: true
templating: { engines: [] }
http_method_override: true
【templating: { engines: [] } 是关键】——它彻底关闭 Twig 引擎，防止控制器意外调用 render() 返回 HTML。若留空或未设，json() 方法在某些路由下仍可能 fallback 到 Twig 渲染。
接着，在控制器中严格使用 json() 方法返回数据，不要混用 render()：
return $this->json(['message' => 'OK', 'data' => $user], Response::HTTP_OK);
统一错误响应格式
Symfony 默认 400+ 错误返回 HTML 页面，Vue 的 catch 拿到的是状态码 200 + 一堆 HTML 文本，根本无法解析。必须重写错误控制器。
第一步：创建 src/Controller/ErrorController.php：
class ErrorController extends AbstractController
{
public function show(Request $request): JsonResponse
{
$statusCode = $request->attributes->get('status_code', 500);
$message = Response::$statusTexts[$statusCode] ?? 'Error';
return $this->json(['error' => $message, 'status' => $statusCode}, $statusCode);
}
}
第二步：在 config/packages/framework.yaml 中指定：
framework:
error_controller: 'App\Controller\ErrorController::show'
这一步不可跳过。否则前端收到 422 错误时，response.json() 会抛出 SyntaxError。
暴露实体为 API 资源（API Platform 方式）
若项目已安装 API Platform（推荐），只需在实体类上加注解即可自动生成 CRUD 接口。
方法一：用 @ApiResource 标记实体
#[ApiResource(mercure: true)]
class Post
{
#[ORMId]
#[ORMGeneratedValue]
#[ORMColumn(type: 'integer')]
private ?int $id = null;
#[ORMColumn(type: 'string', length: 255)]
private string $title;
// getter/setter...
}
方法二：禁用默认 HTML 输出格式
在 config/packages/api_platform.yaml 中设置：
api_platform:
formats:
json: ['application/json']
# 注释掉或删除 html: ['text/html'] 行
【删除 html 格式支持是硬性要求】——否则 /api/posts 在浏览器直接访问仍返回 HTML，破坏前后端分离契约。
配置跨域与认证 Cookie
开发时前端运行在 http://localhost:5173，Symfony 在 http://localhost:8000，必须让浏览器在跨域请求中携带 Cookie。
第一步：设置响应头
在 config/packages/security.yaml 的 firewall 下添加：
main:
cors: true
# 并确保 session 配置含：
session:
cookie_samesite: 'lax'
第二步：前端 fetch 必须带 credentials: 'include'：
fetch('/api/login', { method: 'POST', credentials: 'include', body: JSON.stringify(data) })
第三步：后端响应必须返回 Access-Control-Allow-Credentials: true，且 Access-Control-Allow-Origin 不能为 *——需精确匹配前端域名。
