跳转到主要内容

概览

revolution/laravel-fetch-metadata 是一个用于校验浏览器发送的 Sec-Fetch-* HTTP header 的安全中间件包。你可以根据请求的发起来源、模式、目标以及是否由用户操作触发,来控制允许通过的请求。 借助浏览器内建的安全能力,可以在不影响正常用户体验的前提下,阻止来自恶意来源的非法请求。
在 Laravel 13 中,CSRF 保护的 Origin 校验开始使用 Sec-Fetch-Site header。详情请参考 CSRF 保护
关于 Fetch Metadata 的详细规范,请参考 MDN 文档

安装

注册中间件别名

bootstrap/app.php 中注册中间件别名。
你也可以只使用其中的一部分中间件。别名可以任意修改。

中间件说明

SecFetchSite

Sec-Fetch-Site header 表示请求的发起来源与目标 origin 之间的关系。默认只允许 same-originnone(直接访问)。 详情请参考 MDN 文档

SecFetchMode

Sec-Fetch-Mode header 表示请求的模式。默认允许 navigatecors 详情请参考 MDN 文档

SecFetchDest

Sec-Fetch-Dest header 表示请求目标资源的类型。 详情请参考 MDN 文档

SecFetchUser

Sec-Fetch-User header 表示请求是否由用户操作触发。值只有 ?1(有用户操作)。
使用 SecFetchUser 中间件会同时拦截搜索引擎爬虫和 AI agent。请不要用在需要被索引的公开页面上。

在路由中的使用示例

基本用法

通过参数指定允许值

指定多个参数

不使用别名的情况

组合多个中间件

错误处理

Sec-Fetch-* header 的值不合法时,会抛出 Symfony\Component\HttpKernel\Exception\BadRequestHttpException 可以在 bootstrap/app.php 中自定义响应。

与 CSRF 保护的关系

在 Laravel 13 中,PreventRequestForgery 中间件作为 CSRF 保护的第一步,会通过 Sec-Fetch-Site header 进行 Origin 校验。本包在更细粒度上进一步利用 Fetch Metadata header,可以进一步增强应用的安全性。 详情请参考 CSRF 保护
最新信息请参考 GitHub 仓库
最后修改于 2026年7月18日