Laravel中如何处理表单CSRF令牌_Laravel CSRF防护机制与忽略配置【详解】

419 Page Expired 错误是 laravel csrf 校验失败所致，主因是表单缺失或校验不通过 _Token 字段，常见于未加 @csrf、session 过期、多标签页冲突或 API 路由误配 web 中间件。

为什么提交表单时出现 419 Page Expired 错误

这是 Laravel CSRF 防护机制触发的典型表现，本质是请求中缺失或校验失败了 _token 字段。Laravel 默认要求所有 POST、PUT、PATCH、delete 请求都携带有效的 CSRF token，且该 token 必须与 session 中存储的一致。常见诱因包括：
– 表单未包含 @csrf 指令或 >
– 用户 session 过期（默认 2 小时），但页面长期未刷新
– 多标签页操作导致 session 被覆盖或重置
– 使用 API 路由却未正确配置中间件（如误将 api 路由加到 web 中间件组）

Laravel 表单中正确注入 CSRF token 的三种方式

必须确保每个非 GET 表单都显式携带 token，否则中间件 VerifyCsrfToken 会直接拒绝请求。
推荐按以下优先级使用：

• @csrf Blade 指令 —— 最简洁，自动渲染隐藏 input，值来自 csrf_token()
• {{ csrf_field() }} —— 等价于 @csrf，适合动态拼接字符串场景
• 手动写 —— 仅在需要控制属性（如添加 data-token）时用，易漏写或拼错 name

注意：csrf_token() 函数返回的是当前 session 关联的加密字符串，每次 session 新建都会变化；它不等于 app_KEY 或随机 UUID。

哪些路由可以安全跳过 CSRF 校验

跳过 CSRF 校验不是“关闭防护”，而是明确告诉框架：这些端点天然不依赖 session，也不接受浏览器直接提交的表单。适用场景极有限，常见于：

• 第三方 Webhook 接收端（如 Stripe、微信支付回调），它们无法携带 cookie 或 _token
• 纯 API 接口（已使用 auth:sanctum 或 auth:api 认证），token 通过 Authorization header 传递
• 某些内部服务间调用（需配合 IP 白名单等其他防护）

配置方式是在 app/http/Middleware/VerifyCsrfToken.php 的 $except 数组中添加路径模式：

protected $except = [     'stripe/webhook',     'api/v1/notify/*',     'admin/import/csv' ];

⚠️ 不要写 '*' 或 'api/*' 这类宽泛规则；不要为普通后台表单添加例外；$except 匹配的是路由定义的 URI，不是控制器方法名。

CSRF token 在 ajax 请求中怎么传

Laravel 默认把 token 存在 cookie XSRF-TOKEN 中，并在前端 js 自动读取它填入请求头。前提是满足两个条件：
– 页面响应中包含 XSRF-TOKEN cookie（由 StartSession 和 EncryptCookies 中间件协作完成）
– 前端使用 axios 或 jquery（且启用了 xsrfCookieName / xsrfHeaderName 配置）

如果你用原生 fetch，需手动取值并设置 header：

const token = document.querySelector('meta[name="csrf-token"]').getAttribute('content'); fetch('/post', {   method: 'POST',   headers: {     'X-CSRF-TOKEN': token,     'Content-Type': 'application/json'   },   body: JSON.stringify({ title: 'hello' }) });

对应页面 head 中需有：。这个 meta 标签不是 Laravel 自动插入的，必须自己加。

Laravel 的 CSRF 防护不是开关型配置，而是一套依赖 session 生命周期、中间件顺序和客户端配合的链路。最容易被忽略的是：token 值本身不持久，它随 session 刷新而变；一旦用户长时间停留旧页面，再提交就会 419 —— 这时候不是后端要改配置，而是前端该监听 beforeunload 或用 axios 的 response interceptor 捕获 419 并触发重新登录。