Laravel 基于API的邮件验证失效：持续提示URL无效或已过期

• Laravel签名校验规则：hasValidSignature() 会对完整请求URI（含路由参数）+ 所有查询参数的组合做哈希校验，任何路径改动、参数位置调整、参数增减都会直接导致签名失效。
• 路由与生成链接不匹配：邮件中原始验证链接的路径为 /email/verify/{id}/{hash}，你手动将其修改为 /api/verify-email/{id}，还把原路径中作为路由参数的{hash}挪到了查询串，二者的签名计算基础完全不同。
• 路由命名冲突：你给自定义API路由命名为verification.verify，但Laravel默认的邮件验证通知（MustVerifyEmail特质）默认调用的是未自定义的web端verification.verify路由，而非你编写的API路由。

1. 调整API路由结构 #

让路由参数结构与Laravel默认验证路由对齐，添加必要的signed中间件处理签名校验：

// 放置在api中间件组下（自动带/api前缀）
Route::get('/email/verify/{id}/{hash}', [
    \App\Http\Controllers\ApiAuth\VerifyEmailController::class,
    'index'
])->middleware(['auth', 'signed'])->name('verification.verify');

2. 自定义邮件验证链接生成逻辑 #

重写User模型的verificationUrl方法，让生成的验证链接直接指向API路由：

// App\Models\User 类中添加以下方法
public function verificationUrl(\Illuminate\Notifications\Messages\MailMessage $notification)
{
    return \Illuminate\Support\Facades\URL::signedRoute(
        'verification.verify',
        ['id' => $this->getKey(), 'hash' => sha1($this->email)],
        now()->addMinutes(config('auth.verification.expire', 60))
    );
}

说明：原邮件链接中的36be72d64a3dfec027a14bc40cea3e76424dea05是用户邮箱的SHA1哈希值，与Laravel默认逻辑一致。

3. 重新发起验证流程 #

修改完成后重新触发验证邮件发送，直接使用新生成的邮件链接发起请求，无需手动在Postman中拼接参数。

• 不要手动修改邮件内的链接参数，所有签名均为自动生成，手动调整路径或参数位置必然失效。
• 若路由已添加signed中间件，控制器内的$request->hasValidSignature()判断为冗余逻辑，可直接移除，签名校验由中间件统一处理。
• 若不需要强制走API路径，也可直接修改Laravel默认web端的验证路由逻辑，返回JSON格式响应适配前端API调用。

内容的提问来源于stack exchange，提问作者Umur Alpay