Laravel 如何将API认证默认的api_token参数替换为api_key、key等自定义参数

核心逻辑 #

不需要修改auth:api中间件的核心源码，Laravel 认证系统本身预留了参数自定义的配置入口，通过对应配置调整即可快速实现需求。 #

具体操作步骤 #

1. 定位认证守卫配置 #

打开项目根目录下的config/auth.php，找到当前auth:api中间件绑定的api守卫配置段，默认基础配置如下：

'guards' => [
    'api' => [
        'driver' => 'token',
        'provider' => 'users',
    ],
],

2. 配置自定义令牌参数名 #

Laravel 原生的token驱动认证类（Illuminate\Auth\TokenGuard）内置storage_key配置项，该值就是框架从请求中提取令牌时使用的查询参数名，默认值为api_token。
只需要在上述守卫配置中新增storage_key配置项，填入需要的自定义参数名即可：

'guards' => [
    'api' => [
        'driver' => 'token',
        'provider' => 'users',
        // 替换为自定义参数名，支持api_key、key等任意命名
        'storage_key' => 'api_key',
    ],
],

3. 使配置生效 #

修改完成后执行命令清除配置缓存，让调整生效：
php artisan config:clear #

适配效果 #

调整完成后，原有接口请求格式：

https://www.example.com/api/v2/?api_token=something&action=balance
可直接替换为自定义参数的请求格式：
https://www.example.com/api/v2?api_key=something&action=balance
https://www.example.com/api/v2?key=something&action=balance
所有绑定auth:api中间件的路由，都能正常识别自定义参数名传递的令牌，完成权限校验。

特殊场景适配 #

如果项目使用 Laravel Sanctum、Laravel Passport 这类第三方认证扩展，或者需要针对不同版本的API路由单独适配参数名（比如仅v2版本用api_key、v1版本仍保留api_token），可以通过自定义参数映射中间件实现：

• 新建中间件文件app/Http/Middleware/MapCustomApiToken.php，核心逻辑为将自定义参数值映射到框架默认识别的令牌参数：

public function handle(Request $request, Closure $next)
{
    // 匹配自定义参数值，映射到框架默认识别的api_token参数
    if ($request->has('api_key')) {
        $request->query->set('api_token', $request->get('api_key'));
    }
    return $next($request);
}

• 在路由配置中，将该中间件放在目标路由组的auth:api中间件之前即可，不会影响其他路由组的原有认证逻辑。

注意事项 #

• 生产环境修改配置后需要重新执行配置缓存生成命令php artisan config:cache，不要直接将未缓存的配置文件暴露在生产环境
• 不要直接修改vendor目录下的框架核心代码，后续框架升级会直接覆盖修改，所有自定义逻辑尽量通过配置、自定义中间件的方式实现
• 多版本API共存的项目，优先通过路由级中间件适配自定义参数，不要全局修改认证守卫配置，避免影响低版本接口的兼容性

内容的提问来源于stack exchange，提问作者Sameel Butt