Laravel Passkeys 初步调查(passkeys-server + @laravel/passkeys)

本文基于 laravel/passkeys-server 和 laravel/passkeys 的 README 进行初步调查。两个包目前还未打标签,处于开发中(截至 2026 年 4 月)。

这是什么样的包

在 Laravel 官方仓库中,已公开两个用于实现无密码认证(WebAuthn / passkey)的包。

服务端(PHP):laravel/passkeys-server
客户端(JavaScript):@laravel/passkeys

把两者组合起来,就能在 Laravel 应用中一致地实现 passkey 注册和 passkey 登录。

服务端:`laravel/passkeys-server`

安装与初始化

添加 PHP 包

composer require laravel/passkeys

发布并执行迁移

php artisan vendor:publish --tag=passkeys-migrations
php artisan migrate

在 User 模型上添加 trait 和 contract

use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;
}

需要时也可以发布配置文件。

php artisan vendor:publish --tag=passkeys-config

自动注册的路由

分类	方法	路由	用途
Login (guest)	`GET`	`/passkeys/login/options`	获取认证选项
Login (guest)	`POST`	`/passkeys/login`	验证 passkey 并登录
Confirm (auth)	`GET`	`/passkeys/confirm/options`	获取确认选项
Confirm (auth)	`POST`	`/passkeys/confirm`	passkey 确认
Management (auth)	`GET`	`/user/passkeys/options`	获取注册选项
Management (auth)	`POST`	`/user/passkeys`	保存新 passkey
Management (auth)	`DELETE`	`/user/passkeys/{passkey}`	删除 passkey

`config/passkeys.php` 的主要选项

relying_party_id
allowed_origins
user_handle_secret
timeout
guard
middleware
throttle
redirect

事件

包会触发以下事件。

PasskeyRegistered
PasskeyVerified
PasskeyDeleted

可定制点

LoginAuthorizationCallback(登录授权判定)

通过 Passkeys::authorizeLoginUsing() 控制验证成功后是否允许登录。想终止时返回 false,或抛出 ValidationException。

CustomActions(替换 WebAuthn 处理)

继承 GenerateRegistrationOptions / GenerateVerificationOptions / StorePasskey / VerifyPasskey / DeletePasskey 并绑定到服务容器,可以替换默认行为。

CustomResponses(替换响应)

通过自定义实现 PasskeyLoginResponse 等契约,可以按应用需要修改成功响应(JSON、重定向等)。

客户端:`@laravel/passkeys`

@laravel/passkeys 是负责浏览器端 WebAuthn ceremony 的 JavaScript 客户端。

安装

npm install @laravel/passkeys

基本 API

import { Passkeys } from "@laravel/passkeys";

await Passkeys.register({ name: "My MacBook" });
await Passkeys.verify();

框架辅助函数

React:@laravel/passkeys/react 的 usePasskeyVerify、usePasskeyRegister
Vue:@laravel/passkeys/vue 的 usePasskeyVerify、usePasskeyRegister
Svelte:@laravel/passkeys/svelte 的 usePasskeyVerify、usePasskeyRegister

passkey 自动填充

指定 autofill: true 后,可以在带 autocomplete="... webauthn" 的 input 中显示浏览器的 passkey 选择器。在不支持的环境或用户取消时会回退到常规流程。

带类型的错误

README 中公开了以下错误类。

NotSupportedError
UserCancelledError
PasskeyExistsError
PasskeyError(基类)

SSR 支持

WebAuthn 是浏览器 API,但各框架的 hook 都是 SSR 安全的。在服务器端 isSupported 会被视为 false,组件挂载后会更新为浏览器实际状态。

总结

把 laravel/passkeys-server(PHP)和 @laravel/passkeys(JS)组合起来,就能构建一套完全在 Laravel 内闭环的 passkey 认证栈。
两者目前都还没有正式版本标签,但作为 Laravel 官方生态的一部分,很有可能会成为未来的标准认证手段。
早期采用时,可以按 README 中给出的路由、配置、错误处理、可扩展点为前提来做设计,这样比较安全。

之后 passkey 已经作为 Laravel Fortify 的功能被正式引入。通过 Fortify 启用 passkey 时,不再直接安装 laravel/passkeys-server,而是使用 Features::passkeys()。详情请参考 Laravel Fortify 与启动套件。

laravel/passkeys-server

查看服务端包的最新 README 与实现。