# @capgo/capacitor-passkey 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-passkey/

版本：8\.5\.8
npm 元数据更新时间：2026-10-26T22:23:57.376Z
中文译文更新时间：2026-11-09T02:20:47.465Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-passkey
原文对照：https://npmcn.com/package/%40capgo/capacitor-passkey/?lang=original
项目主页：https://capgo.app/docs/plugins/passkey/
源码仓库：https://github.com/Cap-go/capacitor-passkey

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：444 kB，37 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-04-13T12:32:43.228Z
- 最新版本发布：2026-10-26T22:23:56.856Z
- 近 30 天下载量：143813（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

Capacitor Passey插件,为Capacitor apps配有WebAuthn风格的shim.

## 安装

```sh
npm install @capgo/capacitor-passkey
```

也可以使用：`pnpm add @capgo/capacitor-passkey`、`yarn add @capgo/capacitor-passkey`、`bun add @capgo/capacitor-passkey`

## README

# @ capgo/ 电容器- passkey

在您的 Capacitor app 上添加密码而不重写您的网页登录: 插件可以shim `navigator.credentials` 并转发到iOS和Android上的本地密码API.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-passkey)](https://capgo.app/?ref=plugin_passkey)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_passkey)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_passkey) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-passkey` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加上@capgo/capor-passkey到我的Capacitor应用上,并把它接上。"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_passkey) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_passkey)

![@capgo/capacitor-passkey for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-passkey/main/assets/github-social-preview.png)

## 主要特点

-   **WebAuthn shim (英语)**数字 : `autoShimWebAuthn()` 补丁 `navigator.credentials.create` 财务报告和审定财务报表 `get` 页:1 `publicKey` 请求.
-   **直接 API**数字 : `createCredential()` 财务报告和审定财务报表 `getCredential()` 从您的后端取 JSON 安全 WebAuthn 选项 .
-   **本地 APIs**: 认证 iOS和Android上的信用经理服务.
-   **项目设置**: 可以在 `cap sync`。 。 。 .
-   **支持检查**数字 : `isSupported()` 财务报告和审定财务报表 `getConfiguration()`。 。 。 .
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 在网页上,插件使用浏览器WebAuthn API.

## 为什么这个插件

大多数 Capacitor apps 已经根据 :

```ts
await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });
```

此插件保持该形状为 Capacitor app :

-   它可以自动拍出 `navigator.credentials.create/get` 页:1 `publicKey` 请求.
-   它向iOS和Android上的本地密码API转发了呼叫.
-   它返回类似浏览器的认证对象,这样现有的代码就可以继续工作.
-   它可以在期间自动配置生成的iOS和Android主机项目 `cap sync/update`。 。 。 .
-   它也暴露出当您的后端已经返回了WebAuthn JSON时直接的JSON安全方法.

它没有做什么:

-   它不会给你带来后端挑战.
-   它不会消除您网站主机的需要 `apple-app-site-association` 财务报告和审定财务报表 `assetlinks.json`。 。 。 .
-   它不会让Android本地密码向服务器报告您网站的HTTPS来源. 在Android上,普通的应用程序使用该应用程序的出处(`android:apk-key-hash:...`) (中文(简体) ).

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/passkey/ (英语)](https://capgo.app/docs/plugins/passkey/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的电容安装的版本 .

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-passkey` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
bun add @capgo/capacitor-passkey
```

## 浏览器- 类似设置

1.  配置插件一次进入 `capacitor.config.ts` 或者说 `capacitor.config.json`。 。 。 .
2.  从标准包入口导入插件 .
3.  打电话 `CapacitorPasskey.autoShimWebAuthn()` 一次在应用靴子.
4.  保留您已有的浏览器 `navigator.credentials.create/get` 代码不变.

### 1\. 配置 `capacitor.config.*`

```ts
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'app.capgo.passkey.example',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorPasskey: {
      origin: 'https://signin.example.com',
      autoShim: true,
      domains: [
        'signin.example.com',
      ],
    },
  },
};

export default config;
```

配置密钥 :

-   `origin`:该应用程序的主要HTTPS依赖方源.
-   `domains`: 可选的额外依赖方主机名以本地方式在 `cap sync/update`。 。 。 .
-   `autoShim`: 默认为 `true`。这只控制本地 `cap sync/update` 自动配置钩.

然后同步本地项目 :

```bash
bunx cap sync
```

期间 `cap sync` 编号 : `cap update`,插件自动补丁生成的主机应用程序 :

-   iOS:更新应享权利文件和电线 `CODE_SIGN_ENTITLEMENTS` 如果需要的话.
-   安卓:注射剂 `asset_statements` 元数据并写入生成的字符串资源.

您不需要每次手动编辑主机项目文件 .

### 2\. 在靴子上安装 " Shim "

```ts
import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();
```

这个电话是 `plugins.CapacitorPasskey` 从本地 Capacitor 配置并明确安装 WebAuthn shim .

### 3\. 保留现有的WebAuthn呼叫

之后,你的浏览器风格代码可以保持不变:

```ts
const registration = await navigator.credentials.create({
  publicKey: {
    challenge: crypto.getRandomValues(new Uint8Array(32)),
    rp: {
      id: 'signin.example.com',
      name: 'Example Inc',
    },
    user: {
      id: crypto.getRandomValues(new Uint8Array(32)),
      name: 'ada@example.com',
      displayName: 'Ada Lovelace',
    },
    pubKeyCredParams: [
      { type: 'public-key', alg: -7 },
      { type: 'public-key', alg: -257 },
    ],
  },
});

const authentication = await navigator.credentials.get({
  publicKey: {
    challenge: crypto.getRandomValues(new Uint8Array(32)),
    rpId: 'signin.example.com',
  },
});
```

## 钩子配置

插件钩子只补丁Capacitor生成的本地主机应用文件.

-   它不会碰你的应用程序源代码.
-   它不要求您永久手动编辑 Xcode 或 Android 项目文件 .
-   它不为您发布或生成网站关联文件.

### 直接 JSON 安全 API

如果后端已经返回 `PublicKeyCredentialCreationOptionsJSON` 或者说 `PublicKeyCredentialRequestOptionsJSON`,您可以直接调用插件 :

```ts
import { CapacitorPasskey } from '@capgo/capacitor-passkey';

const registration = await CapacitorPasskey.createCredential({
  origin: 'https://signin.example.com',
  publicKey: registrationOptionsFromBackend,
});

const authentication = await CapacitorPasskey.getCredential({
  origin: 'https://signin.example.com',
  publicKey: requestOptionsFromBackend,
});
```

## 您仍然需要的网站文件

Passkey 只有在您的应用程序与您的网站相同的依赖方域关联时才会工作.

### iOS 网站协会文件

主办单位a `apple-app-site-association` 在您的依赖方域上的文件 :

```text
https://signin.example.com/.well-known/apple-app-site-association
```

示例

```json
{
  "webcredentials": {
    "apps": [
      "ABCDE12345.app.capgo.passkey.example"
    ]
  }
}
```

注释:

-   文件必须使用 HTTP 服务 `200`。 。 。 .
-   不添加一个 `.json` 扩展名.
-   这个 `webcredentials` 域名必须匹配用于密码的依赖方id.
-   插件勾钩为您写入相关域名权限 `cap sync/update`。 。 。 .
-   在iOS 17.4和较新版本上,插件使用浏览器风格的客户端数据 API,所以配置的 HTTPS 来源在 `clientDataJSON`。 。 。 .

### Android 网站协会文件

在 :

```text
https://signin.example.com/.well-known/assetlinks.json
```

示例

```json
[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "app.capgo.passkey.example",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]
```

-   使用与您的依赖方 ID 相同的域名 .
-   包含您需要的每个签名证书指纹, 包括测试时构建的调试 .
-   插件钩子写着 `asset_statements` 元数据及生成的字符串资源 `cap sync/update`。 。 。 .
-   您的网站仍然需要服务 `assetlinks.json` 文档.

## 后端注释

此插件保留了前端的WebAuthn API形状,但本地平台与浏览器后端合同并不相同.

-   iOS 17.4+ 可以编码您为 shim 或直接 API 配置的 HTTPS 来源 .
-   Android 证书管理器有 **没有** 动作像一个特权浏览器应用程序。 原生反应源与Android应用签名(`android:apk-key-hash:...`),而不是自动进入您的网站.
-   在配置了数字资产链接后,Android仍然可以使用与您网站相同的依赖方和密码. 不同的部分是字义 `clientDataJSON.origin` 绳子.
-   如果您的服务器严格验证 `clientDataJSON.origin`,允许Android应用软件与您的网络来源并行.
-   您的后端仍然需要正常的 WebAuthn 挑战生命周期和签名验证 .

## 网络行为

-   在网络上,插件转发到真实的浏览器WebAuthn API.
-   在原生Capacitor上,shim会返回由原生API支持的类似浏览器的认证对象.
-   打电话 `CapacitorPasskey.autoShimWebAuthn()` 在使用浏览器风格的WebAuthn调用之前,曾经在拖曳过程中.
-   有条件的调解目前回归 `false`。 。 。 .

## 示例应用

这个 `example-app/` 文件夹显示自动shim流 :

-   `example-app/capacitor.config.json` 配置插件.
-   `example-app/src/main.js` 进口 `CapacitorPasskey` 从 `@capgo/capacitor-passkey`。 。 。 .
-   `example-app/src/main.js` 电话 `CapacitorPasskey.autoShimWebAuthn()` 在靴子上.
-   实际的注册和认证仍然通过 `navigator.credentials.create/get`。 。 。 .

## API 密码

-   [`shimWebAuthn(...)`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-shimwebauthn)
-   [`getConfiguration()`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-getconfiguration)
-   [`autoShimWebAuthn(...)`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-autoshimwebauthn)
-   [`createCredential(...)`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-createcredential)
-   [`getCredential(...)`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-getcredential)
-   [`isSupported()`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-issupported)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-type-aliases)

电容Passkey插件.

使用 `autoShimWebAuthn()` 以保留 `navigator.credentials.create/get` 密码在一个电容软件内工作.

### shimWebAuthn (...) (英语)

```typescript
shimWebAuthn(options?: ShimWebAuthnOptions | undefined) => void
```

在本地插件上安装浏览器风格的 WebAuthn shim .

闪闪发光 `navigator.credentials.create/get` 页:1 `publicKey` 请求和返回类似浏览器的证书对象.

要手动覆盖自动装入配置时使用此功能 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ShimWebAuthnOptions](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-shimwebauthnoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 获取配置 ()

```typescript
getConfiguration() => Promise<PasskeyRuntimeConfiguration>
```

从主机 Capacitor app 装入插件配置 .

这是 `plugins.CapacitorPasskey` 从 `capacitor.config.*`。 。 。 .

**回返情况:** `Promise<[PasskeyRuntimeConfiguration](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyruntimeconfiguration)>`

**自:** 1.1.0 国家

* * *

### 自动ShimWebAuthn(...)

```typescript
autoShimWebAuthn(options?: ShimWebAuthnOptions | undefined) => Promise<PasskeyRuntimeConfiguration>
```

使用主机应用程序配置安装浏览器风格 shim .

这是保持现有浏览器WebAuthn代码工作的最简单方式: 配置插件在 `capacitor.config.*`,然后在 应用靴子.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ShimWebAuthnOptions](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-shimwebauthnoptions)` |

**回返情况:** `Promise<[PasskeyRuntimeConfiguration](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyruntimeconfiguration)>`

**自:** 1.1.0 国家

* * *

### 创建证书(...)

```typescript
createCredential(options: CreateCredentialOptions) => Promise<PasskeyRegistrationCredential>
```

从 JSON 安全 WebAuthn 请求注册密码 .

当您的后端已经返回时, 此方法很有用 `PublicKeyCredentialCreationOptionsJSON` 形式.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CreateCredentialOptions](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-createcredentialoptions)` |

**回返情况:** `Promise<[PasskeyRegistrationCredential](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyregistrationcredential)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 获得证书(...)

```typescript
getCredential(options: GetCredentialOptions) => Promise<PasskeyAuthenticationCredential>
```

使用 JSON 安全 WebAuthn 请求中存在的密码认证 .

当您的后端已经返回时, 此方法很有用 `PublicKeyCredentialRequestOptionsJSON` 形式.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetCredentialOptions](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-getcredentialoptions)` |

**回返情况:** `Promise<[PasskeyAuthenticationCredential](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticationcredential)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 已支持 ()

```typescript
isSupported() => Promise<PasskeySupportResult>
```

报告当前运行时间是否有密码.

**回返情况:** `Promise<[PasskeySupportResult](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeysupportresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<PluginVersionResult>
```

返回当前平台执行版本标记 .

**回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-pluginversionresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 接口

#### ShimWebAuthn 选项

安装浏览器风格 shim 时使用的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`origin`** | `string` | 可选的HTTPS来源可以编码为iOS 17.4+客户端DataJSON. 当您的 Capacitor app 运行于 `capacitor://localhost` 但你的依赖方期望 `https://signin.example.com`。 。 。 . |
| **`force`** | `boolean` | 即使跑步时间已经暴露了 也要强迫Shim `navigator.credentials`默认为 `false`。 。 。 . |

#### Passkey 运行时配置

从主机的 Capacitor 配置中装入了运行时间配置 .

这是返回的形状 `getConfiguration()`。 。 。 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`autoShim`** | `boolean` | 无论本地人 `cap sync/update` 钩子应自动接通主机项目. 默认为 `true`。 。 。 . |
| **`origin`** | `string` | 由配置驱动的shim安装所使用的可选 HTTPS 来源 。 在iOS 17.4+上,此来源被编码为 `clientDataJSON`。 。 。 . |
| **`domains`** | `string[]` | 与密码使用应用相关的域名. 这些来自 `domains` 在 Capacitor 配置中加上从 `origin` 当可用时. |
| **`platform`** | `'ios' | 'android' | 'web'` | 目前运行时站台. |

#### 通行证

JSON安全注册证书被插件返回.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `string` | Base64url - 编码证书标识符. |
| **`rawId`** | `string` | Base64url - 编码原始证书标识符. |
| **`type`** | `[PasskeyCredentialType](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeycredentialtype)` | 证书类型。 永远 `public-key`。 。 。 . |
| **`authenticatorAttachment`** | `[PasskeyAuthenticatorAttachment](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticatorattachment)` | 平台报告的可选验证器附件 . |
| **`clientExtensionResults`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-record)<string, unknown>` | 平台返回客户端扩展结果. |
| **`response`** | `[PasskeyAuthenticatorAttestationResponseJSON](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticatorattestationresponsejson)` | 登记反应有效载荷. |

#### 密码认证器

JSON安全证明反应有效载荷.

所有二进制字段都由 Base64url 编码.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`clientDataJSON`** | `string` | Base64url - 编码客户端 DataJSON. |
| **`attestationObject`** | `string` | Base64url-编码验证对象. |
| **`publicKey`** | `string` | 由平台提供时可选 Base64url-encode 公钥. |
| **`publicKeyAlgorithm`** | `number` | 平台提供的可选公钥算法. |
| **`transports`** | `string[]` | 由站台提供可选运输列表. |
| **`authenticatorData`** | `string` | 可选基数64url-编码验证器数据. |

#### 创建证书选项

插件运输直接注册申请.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`publicKey`** | `[PasskeyPublicKeyCredentialCreationOptionsJSON](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeypublickeycredentialcreationoptionsjson)` | JSON安全注册申请. |
| **`origin`** | `string` | 可选的HTTPS来源用于iOS 17.4+浏览器风格的客户端DataJSON. |

#### Passkey PublicKey 证书创建选项

JSON安全注册申请选项.

所有二进制字段必须被 Base64url 编码 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`challenge`** | `string` | Base64url - 编码挑战. |
| **`rp`** | `[PasskeyRelyingParty](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyrelyingparty)` | 赖党信息. |
| **`user`** | `[PasskeyUserEntity](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyuserentity)` | 用户信息. |
| **`pubKeyCredParams`** | `PasskeyCredentialParameter[]` | 支持的证书算法. |
| **`timeout`** | `number` | 以毫秒计的可选超时提示 . |
| **`excludeCredentials`** | `PasskeyCredentialDescriptor[]` | 在登记期间必须排除的可选证书. |
| **`authenticatorSelection`** | `[PasskeyAuthenticatorSelection](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticatorselection)` | 可选的认证者偏好. |
| **`attestation`** | `[PasskeyAttestation](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyattestation)` | 可选的证明偏好. |
| **`hints`** | `string[]` | 从现代WebAuthn工具包使用的JSON格式复制的可选提示. |
| **`extensions`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-record)<string, unknown>` | 可选扩展复制为 JSON 请求 . |

#### 密码存储方

JSON安全依赖党信息.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `string` | 依赖方识别码. 如果省略,shim在可能时会从所配置的源得到. |
| **`name`** | `string` | 人可读取依赖党名. |

#### 密码用户实体

JSON安全 WebAuthn 用户实体.

二进制标识符必须被 Base64url 编码 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `string` | Base64url - 编码用户手柄. |
| **`name`** | `string` | 认证者显示的用户名 . |
| **`displayName`** | `string` | 可选显示名由认证者显示. |

#### 通行证

JSON - 安全证书参数条目.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`type`** | `[PasskeyCredentialType](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeycredentialtype)` | 证书类型。 仅 `public-key` 被支持. |
| **`alg`** | `number` | COSE算法标识符. |

#### 密码键证书描述符

JSON安全地代表了公用钥匙证书的描述.

二进制标识符必须被 Base64url 编码 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `string` | Base64url - 编码证书标识符. |
| **`type`** | `[PasskeyCredentialType](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeycredentialtype)` | 证书类型。 仅 `public-key` 被支持. |
| **`transports`** | `string[]` | 从 WebAuthn 复制的可选传输提示 . |

#### 密码校正器选择

JSON安全验证员选择选项.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`authenticatorAttachment`** | `[PasskeyAuthenticatorAttachment](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticatorattachment)` | 可选验证器附件提示 . |
| **`residentKey`** | `[PasskeyResidentKey](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyresidentkey)` | 可选居民关键选择. |
| **`requireResidentKey`** | `boolean` | 遗留居民关键要求旗. |
| **`userVerification`** | `[PasskeyUserVerification](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyuserverification)` | 可选用户验证偏好. |

#### 密码验证证书

JSON-安全认证证书被插件返回.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `string` | Base64url - 编码证书标识符. |
| **`rawId`** | `string` | Base64url - 编码原始证书标识符. |
| **`type`** | `[PasskeyCredentialType](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeycredentialtype)` | 证书类型。 永远 `public-key`。 。 。 . |
| **`authenticatorAttachment`** | `[PasskeyAuthenticatorAttachment](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticatorattachment)` | 平台报告的可选验证器附件 . |
| **`clientExtensionResults`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-record)<string, unknown>` | 平台返回客户端扩展结果. |
| **`response`** | `[PasskeyAuthenticatorAssertionResponseJSON](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyauthenticatorassertionresponsejson)` | 自动响应有效载荷. |

#### 密码认证器

JSON安全断言反应有效载荷.

所有二进制字段都由 Base64url 编码.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`clientDataJSON`** | `string` | Base64url - 编码客户端 DataJSON. |
| **`authenticatorData`** | `string` | Base64url-编码验证器数据. |
| **`signature`** | `string` | Base64url-编码签名. |
| **`userHandle`** | `string | null` | 可选碱基64url-编码用户手柄. |

#### 获取证书选项

插件传输的直接认证请求 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`publicKey`** | `[PasskeyPublicKeyCredentialRequestOptionsJSON](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeypublickeycredentialrequestoptionsjson)` | JSON安全认证请求. |
| **`mediation`** | `string` | 可选的调解提示. `conditional` 目前回到一个明确的提示. |
| **`origin`** | `string` | 可选的HTTPS来源用于iOS 17.4+浏览器风格的客户端DataJSON. |
| **`preferImmediatelyAvailableCredentials`** | `boolean` | 优先存储在本地设备上,跳过混合式/相近式拾取器. 失败者 `NotAllowedError` 当不存在本地证书时。 在网络和iOS 15.被忽略. |

#### Passkey PublicKey 重要请求选项

JSON-安全认证请求选项.

所有二进制字段必须被 Base64url 编码 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`challenge`** | `string` | Base64url - 编码挑战. |
| **`timeout`** | `number` | 以毫秒计的可选超时提示 . |
| **`rpId`** | `string` | 可选依赖方标识符. 如果省略,shim在可能时会从所配置的源得到. |
| **`allowCredentials`** | `PasskeyCredentialDescriptor[]` | 可选允许列表复制自 WebAuthn . |
| **`userVerification`** | `[PasskeyUserVerification](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-passkeyuserverification)` | 可选用户验证偏好. |
| **`hints`** | `string[]` | 从现代WebAuthn工具包使用的JSON格式复制的可选提示. |
| **`extensions`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-passkey/#readme-record)<string, unknown>` | 可选扩展复制为 JSON 请求 . |

#### 密码支持结果

当前运行时间的密码支持状态 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`available`** | `boolean` | 当前运行时间是否有密码可用 . |
| **`conditionalMediation`** | `boolean` | 有无有条件的调解. |
| **`platform`** | `'ios' | 'android' | 'web'` | 当前平台标识符 . |

#### 插件变压器

插件版本有效载荷 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`version`** | `string` | 目前平台实施情况报告的版本标识符. |

### 类型异名

#### Passke 证书类型

支持的 WebAuthn 证书类型 .

`'public-key'`

#### 密码校正

支持认证器附件值 .

`'platform' | 'cross-platform'`

#### 记录

构造 T 类型 K 的一组属性类型

`{ [P in K]: T; }`

#### 密码

支持居民关键偏好.

`'discouraged' | 'preferred' | 'required'`

#### 密码用户验证

支持用户验证偏好.

`'discouraged' | 'preferred' | 'required'`

#### 密码交换站

支持的证明偏好.

`'none' | 'indirect' | 'direct' | 'enterprise'`

## 常见问题

### @capgo/capacitor-passkey 是什么？

Capacitor Passey插件,为Capacitor apps配有WebAuthn风格的shim\.

### 如何安装 @capgo/capacitor-passkey？

在项目目录运行 npm install @capgo/capacitor-passkey，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-passkey 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-passkey 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-passkey 可以商用吗？

@capgo/capacitor-passkey 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-passkey 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-passkey 在 2026/10/09 – 2026/11/07 这 30 天内被下载 143,813 次，日均约 4,794 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-passkey 还在维护吗？

最新版本 8\.5\.8 发布于 2026/10/27（13 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。