网站开发框架之Laravel的CSRF令牌自动校验

Laravel框架的CSRF令牌自动校验机制，本质上是通过中间件在每次POST、PUT、PATCH、DELETE请求进入控制器之前，自动比对请求中携带的token值与Session中存储的token值是否一致。如果不一致，框架会直接抛出TokenMismatchException异常并返回419状态码。开发者不需要手动写校验逻辑，只要在表单中加入@csrf指令或者在API路由中配置好中间件，整个流程就会自动跑通。这套机制的核心在于VerifyCsrfToken中间件、Session存储以及Blade模板引擎的配合，三者缺一不可。

很多开发者在实际项目中遇到CSRF校验失败的问题，要么是表单没加token字段，要么是AJAX请求没带X-CSRF-TOKEN头，要么是Session配置不对导致token无法持久化。下面我会从原理、配置、常见问题排查、特殊场景处理这几个维度，把Laravel的CSRF自动校验彻底讲透。

一、CSRF攻击的本质与Laravel的防御思路

CSRF全称Cross-Site Request Forgery，跨站请求伪造。攻击者诱导已登录用户访问恶意页面，该页面自动向目标网站发送请求，利用用户的Cookie完成非法操作。比如用户已经登录了银行网站，攻击者在另一个页面放了一张图片，src指向银行的转账接口，浏览器会自动带上用户的Cookie，钱就被转走了。

Laravel的防御思路非常直接：给每个用户会话生成一个随机的、不可预测的token，每次表单提交或非GET请求都必须携带这个token。服务器收到请求后验证token是否匹配，匹配才放行。因为攻击者无法读取目标网站的页面内容（同源策略限制），所以拿不到这个token，伪造的请求自然会被拦截。

二、Laravel CSRF校验的核心组件拆解

Laravel的CSRF防御由三个核心部分组成：

第一是VerifyCsrfToken中间件。这个中间件在HTTP内核中注册，默认对web路由组生效。它的工作流程是：从Session中读取_token，从请求中获取token（优先从请求参数_token取，其次从X-CSRF-TOKEN请求头取），然后比对。比对失败就抛异常。

第二是Session存储。CSRF token默认存储在Session中，所以Session驱动必须正常工作。如果你用的是file驱动，确保storage目录有写权限；如果用Redis，确保连接正常。Session不工作，token就存不进去，校验必然失败。

第三是Blade模板的@csrf指令。这个指令会在表单中自动生成一个隐藏的input字段，name为_token，value为当前Session中的CSRF token。开发者只需要在form标签内加一行@csrf就行了。

<form method="POST" action="/profile">
    @csrf
    <!-- 其他表单字段 -->
    <input type="text" name="name">
    <button type="submit">提交</button>
</form>

渲染后的HTML会变成这样：

<form method="POST" action="/profile">
    <input type="hidden" name="_token" value="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890">
    <input type="text" name="name">
    <button type="submit">提交</button>
</form>

三、AJAX请求中如何自动携带CSRF Token

前端用Axios、jQuery或者原生fetch发AJAX请求时，不能像表单那样自动带上@csrf生成的隐藏字段，需要手动设置请求头。Laravel官方推荐的做法是在页面的meta标签中输出token，然后JS读取并设置到请求头中。

<meta name="csrf-token" content="{{ csrf_token() }}">

然后在JS中统一配置：

// Axios示例
axios.defaults.headers.common['X-CSRF-TOKEN'] = document.querySelector('meta[name="csrf-token"]').getAttribute('content');

// jQuery示例
$.ajaxSetup({
    headers: {
        'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
    }
});

如果你用的是Laravel自带的前端脚手架，这些配置在bootstrap.js中已经帮你写好了，开箱即用。但如果是自己搭建的前后端分离项目，这一步千万别漏掉，否则所有AJAX的POST请求都会返回419。

四、路由层面的CSRF中间件配置详解

在Laravel的app/Http/Kernel.php中，VerifyCsrfToken中间件默认被分配给web中间件组。这意味着所有走web.php的路由都会自动进行CSRF校验。而api.php默认不带这个中间件，因为API通常用token认证而非Session。

如果你需要对某些路由豁免CSRF校验，有几种方式。第一种是在VerifyCsrfToken中间件的$except属性中添加路由：

// app/Http/Middleware/VerifyCsrfToken.php
protected $except = [
    '/webhook/paypal',
    '/api/notification/*',
];

第二种是在路由定义时用withoutMiddleware方法：

Route::post('/webhook/paypal', [PaypalController::class, 'handle'])
    ->withoutMiddleware([\App\Http\Middleware\VerifyCsrfToken::class]);

需要注意的是，豁免CSRF校验的路由一定要有其他安全机制，比如签名验证、IP白名单等，否则就是把大门敞开了。

五、CSRF校验失败的常见原因与排查方法

实际开发中CSRF校验失败的情况非常多，我总结了最常见的几种：

第一种，Session没启动或者驱动异常。检查.env文件中SESSION_DRIVER的值，确认对应的驱动服务正常运行。可以用php artisan session:table检查数据库session表是否存在。

第二种，表单没有加@csrf或者token字段被前端框架意外删除。有些前端框架在处理表单序列化时会过滤掉隐藏字段，导致token没发出去。检查Network面板中请求体里是否有_token字段。

第三种，AJAX请求的Content-Type不对。如果你把Content-Type设成了application/json，而token放在请求体里，Laravel的中间件默认不会从JSON body中读取token。解决办法是把token放在请求头X-CSRF-TOKEN中，或者在中间件中扩展读取逻辑。

第四种，域名跨域导致Session丢失。如果前端和后端不在同一个域名下，浏览器不会自动带上Cookie，Session就无法维持，token自然对不上。这种情况需要配置CORS并设置withCredentials。

// config/cors.php
'supports_credentials' => true,
'allowed_origins' => ['https://your-frontend.com'],

前端fetch请求也要加credentials: 'include'。

六、API场景下的CSRF处理策略

严格来说，RESTful API不应该依赖Session和CSRF token，而应该用Bearer Token、API Key或者OAuth2来认证。Laravel的Sanctum和Passport就是干这个的。但如果你的API同时也被浏览器直接调用（比如SPA应用），还是需要防CSRF。

Laravel Sanctum提供了一种混合方案：前端通过/sanctum/csrf-cookie接口先获取一个加密的CSRF cookie，然后在后续请求中带上X-XSRF-TOKEN头。这比传统的Session token更适合SPA架构。

// 获取CSRF cookie
axios.get('/sanctum/csrf-cookie').then(response => {
    // 后续请求自动携带X-XSRF-TOKEN
    axios.post('/api/update', data);
});

这种方式的好处是不需要在页面中手动注入meta标签，Sanctum会自动处理cookie的读取和设置。

七、自定义CSRF校验逻辑的进阶用法

虽然Laravel默认的自动校验已经够用，但有些场景需要自定义。比如你想记录每次CSRF失败的请求信息用于安全审计，可以在VerifyCsrfToken中间件中重写handle方法：

public function handle($request, Closure $next)
{
    $token = $this->getTokenFromRequest($request);

    if ($this->isReading($request) || $this->tokenMatches($request, $token)) {
        return $this->addCookieToResponse($request, $next($request));
    }

    // 自定义：记录失败日志
    Log::warning('CSRF token mismatch', [
        'ip' => $request->ip(),
        'url' => $request->fullUrl(),
        'user_agent' => $request->userAgent(),
    ]);

    throw new TokenMismatchException('CSRF token验证失败');
}

还有一种情况是你想动态决定哪些路由需要CSRF校验，可以在中间件中根据路由名称或模式来判断，而不是用固定的$except列表。

八、Laravel版本差异与注意事项

Laravel 10和11在CSRF机制上没有大的变化，但有一些细节调整。比如Laravel 11的路由文件结构变了，web.php和api.php的位置和注册方式有改动，但CSRF中间件的工作原理完全一致。Laravel 11还强化了对HTTPS的要求，生产环境如果没开HTTPS，某些浏览器会阻止Cookie传输，间接导致CSRF校验失败。

另外，从Laravel 9开始，框架引入了加密cookie的机制，CSRF token也会被加密存储。这意味着即使有人拿到了Session文件，也无法直接读出token值，安全性更高。但前提是APP_KEY配置正确，否则加密解密会失败，导致token校验异常。

九、总结与最佳实践

Laravel的CSRF自动校验是一套成熟、可靠的安全机制，开发者需要做的就是：确保Session正常工作、表单加@csrf、AJAX带正确的请求头、跨域场景配置好CORS和credentials。遇到419错误不要慌，按照上面的排查思路一步步来，基本都能定位到问题。安全无小事，CSRF防护是Web应用的基础防线，Laravel已经帮你把最难的部分做好了，剩下的就是正确使用它。

网站开发框架之Laravel的CSRF令牌自动校验

服务指南

帮助中心