> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 对 laravel/passkeys-server(PHP)与 @laravel/passkeys(npm)进行初步调查。整理安装、User 模型集成、路由、配置、事件、前端 API、带类型的错误以及 SSR 支持。

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

## 这是什么样的包

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

* 服务端(PHP):[`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* 客户端(JavaScript):[`@laravel/passkeys`](https://github.com/laravel/passkeys)

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

## 服务端:`laravel/passkeys-server`

### 安装与初始化

<Steps>
  <Step title="添加 PHP 包">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="发布并执行迁移">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="在 User 模型上添加 trait 和 contract">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

    class User extends Authenticatable implements PasskeyUser
    {
        use PasskeyAuthenticatable;
    }
    ```
  </Step>
</Steps>

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

```bash theme={null}
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`

### 可定制点

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback(登录授权判定)">
    通过 `Passkeys::authorizeLoginUsing()` 控制验证成功后是否允许登录。想终止时返回 `false`,或抛出 `ValidationException`。
  </Accordion>

  <Accordion title="CustomActions(替换 WebAuthn 处理)">
    继承 `GenerateRegistrationOptions` / `GenerateVerificationOptions` / `StorePasskey` / `VerifyPasskey` / `DeletePasskey` 并绑定到服务容器,可以替换默认行为。
  </Accordion>

  <Accordion title="CustomResponses(替换响应)">
    通过自定义实现 `PasskeyLoginResponse` 等契约,可以按应用需要修改成功响应(JSON、重定向等)。
  </Accordion>
</AccordionGroup>

## 客户端:`@laravel/passkeys`

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

### 安装

```bash theme={null}
npm install @laravel/passkeys
```

### 基本 API

```js theme={null}
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 中给出的路由、配置、错误处理、可扩展点为前提来做设计,这样比较安全。

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

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  查看服务端包的最新 README 与实现。
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  查看客户端包的最新 README 与 API。
</Card>

<Card title="Laravel Fortify 与启动套件" icon="shield-check" href="/zh/advanced/fortify">
  解析通过 Fortify 启用 passkey 的步骤,以及与启动套件的关系。
</Card>


## Related topics

- [Laravel Fortify 与 Starter Kit](/zh/advanced/fortify.md)
- [Laravel LSP — 通过 Language Server Protocol 扩展 IDE 能力](/zh/blog/laravel-lsp-introduction.md)
- [laravel/symfony-on-cloud — 在 Laravel Cloud 上运行 Symfony 应用](/zh/blog/symfony-on-cloud-introduction.md)
- [Laravel Package Skeleton — 官方包开发用启动模板](/zh/blog/package-skeleton-introduction.md)
- [2026 年 4 月 Laravel 更新](/zh/blog/changelog/202604.md)