PHPCSRF保护在Laravel中默认吗

wen PHP项目 2026-07-08 1

Laravel中的CSRF保护：默认开启还是需要手动配置？深度解析与实战指南

目录导读

CSRF攻击是什么？为什么Laravel如此重视？
Laravel的CSRF保护机制：默认开启还是默认关闭？
深入Laravel的CSRF中间件工作原理
如何在Laravel中配置、禁用或自定义CSRF保护？
常见问题与解答（FAQ）
总结与最佳实践

CSRF攻击是什么？为什么Laravel如此重视？

跨站请求伪造（CSRF） 是一种常见的Web安全漏洞，攻击者诱导用户点击恶意链接或访问恶意网站，从而在用户不知情的情况下，以用户身份向目标网站发起请求，用户登录银行系统后，访问了恶意网站，该网站自动发起转账请求，由于浏览器自动携带了用户的Cookie,银行端会误认为这是用户本人的合法操作。

PHPCSRF保护在Laravel中默认吗

Laravel作为现代PHP框架，将安全性视为核心设计原则，框架内置了强大的CSRF保护机制，避免开发者因为疏忽而引入安全漏洞，理解Laravel如何默认处理CSRF,是构建安全应用的第一步。

问：CSRF攻击只影响POST请求吗？
答：理论上所有可能改变服务器状态的HTTP方法（POST、PUT、DELETE、PATCH）都可能受影响，但GET请求通常不被视为安全操作,Laravel默认保护所有非GET请求。

Laravel的CSRF保护：默认开启还是默认关闭？

答案：Laravel默认开启CSRF保护。 这是框架为所有开发者设定的安全基线。

当你创建新的Laravel项目后，App\Http\Kernel 中的 $middlewareGroups 数组（通常在 web 中间件组中）已经包含了 \App\Http\Middleware\VerifyCsrfToken 中间件，所有通过 Route::post()、Route::put()、Route::delete() 等定义的POST/PUT/DELETE/PATCH路由,都会自动要求携带有效的CSRF令牌。

如何验证默认开启？

创建一个简单的POST路由（不包含csrf_field或@csrf指令）。
使用Postman或curl直接发送POST请求。
你将会收到 419 Page Expired 错误页面,这正是CSRF令牌验证失败的结果。

问：哪些路由不会被CSRF保护？
答：通过 Route::get() 定义的GET路由、使用 Route::fallback() 定义的回退路由，以及显式在 $except 属性中排除的路由,不会被CSRF保护。

深入Laravel的CSRF中间件工作原理

1 令牌生成与传递

生成：每个用户会话初次访问时，Laravel自动生成一个随机字符串作为CSRF令牌，存储在 session 中（键名通常是 _token）。
传递到视图：在Blade模板中，你使用 @csrf 指令（等价于 <input type="hidden" name="_token" value="...">）将令牌嵌入表单，或者，在使用Axios等前端库时，Laravel会自动将令牌注入到页面头部<meta>标签中（通过 csrf_token() 辅助函数）。

2 验证流程

用户提交表单时，POST/PUT等请求中的 _token 参数（或 X-CSRF-TOKEN 请求头）会被发送到服务器。
VerifyCsrfToken 中间件拦截请求，从请求中提取令牌,并与当前会话中的令牌进行比较。
如果两者匹配，请求继续执行（通过 $next($request)），如果不匹配，中间件抛出 TokenMismatchException,最终返回419错误页面。

3 对AJAX请求的特殊处理

Laravel推荐前端在发送AJAX请求时，在请求头中添加 X-CSRF-TOKEN 或 X-XSRF-TOKEN，默认情况下，当你使用 resources/js/bootstrap.js 中提供的Axios配置时，Laravel会自动从 meta 标签读取令牌并添加到请求头，对于普通JS fetch 或 jQuery,需要手动设置。

如何在Laravel中配置、禁用或自定义CSRF保护？

1 默认使用（无需额外配置）

你只需在Blade表单中加入 @csrf,Laravel就会自动处理一切。

<form method="POST" action="/submit">
    @csrf
    <!-- 其他表单字段 -->
</form>

2 排除特定路由（白名单）

某些情况下，你需要为外部API或第三方Webhook禁用CSRF，在 app/Http/Middleware/VerifyCsrfToken.php 的 $except 属性中添加：

protected $except = [
    'webhook/stripe',
    'api/*',  // 注意：API路由组通常不使用web中间件，但若你用了则需要排除
];

访问 /webhook/stripe 的任何POST请求都不会验证CSRF令牌。

3 完全禁用CSRF保护（不推荐）

如果想在整个 web 路由组中禁用，可以移除Kernel中的 VerifyCsrfToken 中间件，但强烈不建议这样做，除非你提供了其他等效的安全措施（如基于签名的API密钥验证）。

4 自定义令牌验证逻辑

你可以继承 VerifyCsrfToken 中间件并重写 tokensMatch 方法，实现自定义验证规则（例如允许来自特定IP的请求跳过验证）,但仅限高级用户使用。

问：如果我的前端是Vue/React单页应用（SPA），CSRF令牌是否依然有效？
答：有效，Laravel通过 csrf_token() 函数生成令牌，你可以通过API返回它，或将其嵌入到初始页面<meta>标签中，前端每次发送非GET请求时，从meta标签或Cookie中读取令牌并添加到请求头即可。

常见问题与解答（FAQ）

Q1：我收到419错误，但明明已经加了@csrf，为什么？
A：可能原因包括：

用户会话过期了（登录超时），需要重新生成令牌。
使用了多个标签页或浏览器窗口，导致Cookie/session冲突。
在AJAX请求中，忘记设置请求头 X-CSRF-TOKEN 或 X-XSRF-TOKEN。
排除路由配置错误,导致中间件未正确应用到路由。

Q2：CSRF保护会影响API路由吗？
A：默认不会，Laravel为 api 中间件组不包含 VerifyCsrfToken，因为API通常使用token-based认证（如JWT或Passport），如果你手动将API路由放到 web 组中,则会受影响。

Q3：是否可以在多个请求间复用同一CSRF令牌？
A：Laravel的令牌是会话级别的，会话期间不变，但重新登录、会话垃圾回收后，令牌会变，这不会导致安全问题，因为一旦令牌泄露,攻击者依然需要同时拥有Cookie。

Q4：CSRF保护与CORS（跨域资源共享）有什么关系？
A：两者独立但互补，CSRF保护的是请求来源的真实性（防止伪造请求），CORS控制的是浏览器是否允许跨域请求,Laravel的CSRF保护不依赖于CORS配置。

总结与最佳实践

核心结论：Laravel的CSRF保护默认开启，且面向所有非GET请求，这是框架安全性的基石，无需手动启用,但必须正确使用。

最佳实践建议：

始终在表单中使用 @csrf：不要遗漏任何一个POST/PUT/DELETE表单。
正确配置AJAX请求：利用Laravel提供的 csrf_token() 和 meta 标签，结合前端框架的默认配置（如Axios的 withCredentials: true）。
仅对可信第三方禁用CSRF：如支付通知Webhook，确保这些路由有独立的签名验证机制。
定期更新Laravel版本：安全修复通常包含CSRF机制的增强，如对 X-XSRF-TOKEN Cookie的防护。
避免将敏感路由放在 $except 中：除非绝对必要,否则不要为内部表单排除CSRF。

通过理解Laravel的CSRF保护机制，你可以在享受安全性的同时，灵活适配特殊需求，Web安全没有“一刀切”的方案，但Laravel为你提供了一个坚固的起点，如果你遇到任何CSRF相关的问题，请优先检查Token是否正确传递、会话是否有效,以及中间件是否被错误排除。