Laravel中JWT多用户白名单跳过鉴权的核心是让特定请求完全跳过auth:xxx中间件，不触发JWT解析、payload验证及黑名单检查；需通过IP白名单中间件（注册于全局栈且位于TrustProxies之后、Authenticate之前）或路由前缀排除方式实现，严禁在payload或Authenticate中间件中硬编码绕过逻辑。
在 Laravel 中实现 JWT 多用户接口的白名单跳过鉴权，核心不是“绕过 JWT”，而是让特定请求（如白名单 IP 或特定路径）**不进入 JWT 校验流程**，同时保持其他接口严格受控。这需要分层处理：IP 层过滤、路由层分流、中间件层隔离。
一、明确白名单作用域：是跳过整个认证，还是跳过 JWT 校验？
JWT 多用户（如 users/admins/merchants）通常对应多个 guard（auth:api、auth:admin 等）。白名单应跳过的是「鉴权中间件」本身，而非修改 JWT 解析逻辑。否则容易导致：
• 同一个 token 被不同 guard 错误复用
• 黑名单失效或跨 guard 冲突
• Auth::user() 在白名单请求中仍为 null（因 guard 未切换）
所以正确做法是：对白名单请求，**完全跳过 auth:xxx 中间件**，不触发任何 JWT 解析、payload 验证、黑名单检查。
二、按 IP 白名单跳过 JWT 中间件
适用于运维接口、健康检查、Webhook 回调等需固定 IP 访问的场景。关键点：
- 确保
App\Http\Middleware\TrustProxies已正确配置，$request->ip()返回真实客户端 IP - 白名单中间件必须注册在全局
$middleware栈，且位置早于所有 auth 中间件 - 匹配成功后直接
return $next($request)，不向下传递
示例中间件 app/Http/Middleware/SkipJwtForWhitelist.php：
（不继承 ThrottleRequests，仅做条件跳过）
public function handle(Request $request, Closure $next)
{
$ip = $request->ip();
$whitelist = config('auth.whitelist_ips', []);
if (in_array($ip, $whitelist)) {
// 跳过后续所有中间件（含 auth:api、auth:admin 等）
return $next($request);
}
return $next($request);
}
在 app/Http/Kernel.php 的 $middleware 数组中，把它放在 TrustProxies::class 之后、Authenticate::class 之前。
三、按路由前缀白名单跳过 JWT
适用于开放给第三方调用的免鉴权接口，如 /api/public/health、/api/webhook/stripe。操作更轻量：
- 不改中间件，只在路由定义时排除 JWT 中间件
- 多 guard 场景下，确保这些路由不被
middleware('auth')或middleware('auth:api')包裹
示例：
Route::prefix('public')->group(function () {
Route::get('/health', [HealthController::class, 'check']);
Route::post('/webhook/{service}', [WebhookController::class, 'handle'])
->where('service', 'stripe|paypal');
});
该组路由默认无中间件。若项目全局应用了 middleware('auth:api')，需显式清除：
Route::middleware([])->group(function () {
Route::prefix('public')->group(...);
});
四、注意多 guard 下的陷阱
当存在 auth:api、auth:admin、auth:merchant 多个 guard 时，白名单设置必须与 guard 使用方式解耦：
- 不要在
getJWTCustomClaims()里加'bypass' => true—— JWT payload 一旦签发就不可变，无法动态跳过校验 - 不要在
Authenticate中间件里写if ($request->is('api/public/*')) return $next($request)—— 这属于硬编码，违反中间件职责分离 - 避免使用
Auth::shouldUse('api')或Auth::guard('admin')在白名单逻辑中 —— 白名单请求本就不该触发 Auth 实例初始化
真正干净的做法，是让白名单请求从一开始就不触碰任何 guard 和 provider 的加载逻辑。
