# @capawesome/capacitor-passkeys 中文文档

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

版本：0\.1\.2
npm 元数据更新时间：2026-09-02T08:23:01.838Z
中文译文更新时间：2026-11-09T07:08:46.594Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-passkeys
原文对照：https://npmcn.com/package/%40capawesome/capacitor-passkeys/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/passkeys/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

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

- 包体积（解压后）：214 kB，45 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T06:21:36.679Z
- 最新版本发布：2026-09-02T08:23:01.444Z
- 近 30 天下载量：4359（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

在Android,iOS,和Web上创建并认证密码(WebAuthn)的电容插件.

## 安装

```sh
npm install @capawesome/capacitor-passkeys
```

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

## README

# 密码插件

用于创建和认证的电容插件 [密码](https://fidoalliance.org/passkeys/) 基于 [网络认证](https://www.w3.org/TR/webauthn-2/) 标准.

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

Capacitor Passkeys插件是Capacitor App最完整的密码认证解决方案之一. 以下是一些关键特征:

-   🔐 **密码创建**: 以平台验证器注册新的密码.
-   🔑 **密码认证**: 认证用户已有的密码.
-   🌐 **WebAuthn 标准**: 使用WebAuthn JSON序列化,所以任何WebAuthn服务器库工作不变.
-   📱 **可用性检查**:检查设备上是否有密码.
-   🖥️ **网络支持**:通过原生WebAuthn浏览器API提供完整网页支持.
-   🤝 **兼容性**: 与 [生物计量](https://capawesome.io/docs/sdks/capacitor/biometrics/) 财务报告和审定财务报表 [奥奥特](https://capawesome.io/docs/sdks/capacitor/oauth/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

Passkeys 插件通常用于应用程序认证的现代化,例如:

-   **无密码登录**:让用户使用密码进行认证,而不是输入密码.
-   **密码**:让现有用户在签入其现有证书后为其账户注册密码.
-   **逐步加强**: 检查用 `isAvailable()` 是否在设备上支持密码,并作为您已有的登录的替代品提供密码.
-   **服务器集成**:通过WebAuthn服务器库传递任何WebAuthn服务器库的选项和结果,这要归功于WebAuthn JSON序列化.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-passkeys` plugin in my project.
```

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

```bash
npm install @capawesome/capacitor-passkeys
npx cap sync
```

### 机器人

在Android上,Passkey在Android 9(API 第28级)上得到支持,更高处有可用的证书提供商(如Google密码管理员).

#### 变量

此插件将使用以下工程变量( 在您的应用程序中定义) `variables.gradle` 文件名 :

-   `$androidxCredentialsVersion` 版本 `androidx.credentials:credentials` 财务报告和审定财务报表 `androidx.credentials:credentials-play-services-auth` (默认 : `1.5.0`(中文(简体) )

#### 数字资产链接

您的应用必须和依赖方的域域相关( Name`rp.id` 编号 : `rpId`)使用 [数字资产链接](https://developers.google.com/digital-asset-links)。为此,托管 JSON 文件 `https://<your-domain>/.well-known/assetlinks.json` 代表大会 `common.get_login_creds` 允许您的应用程序 :

```json
[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"
      ]
    }
  }
]
```

替换 `com.example.app` 上面有你的应用软件的标识 还有你的应用软件的签名证书的SHA -256指纹 否则,插件方法将用 `DOMAIN_NOT_ASSOCIATED` 错误代码 .

### iOS系统

在iOS上,在iOS 15上和上方支持密码.

#### 相关领域

您的应用必须和依赖方的域域相关( Name`rp.id` 编号 : `rpId`) (中文(简体) ). 为此,增加: [相关领域](https://developer.apple.com/documentation/xcode/supporting-associated-domains) 能力 `webcredentials` 应用程序的服务类型 :

```xml
<key>com.apple.developer.associated-domains</key>
<array>
  <string>webcredentials:example.com</string>
</array>
```

此外,主办方 [`apple-app-site-association`](https://developer.apple.com/documentation/xcode/supporting-associated-domains) 文件位于 `https://<your-domain>/.well-known/apple-app-site-association`数字 :

```json
{
  "webcredentials": {
    "apps": ["TEAMID.com.example.app"]
  }
}
```

替换 `TEAMID` 与您的 Apple 开发团队 ID 和 `com.example.app` 与您的应用程序的捆绑标识符。 否则,插件方法将用 `DOMAIN_NOT_ASSOCIATED` 错误代码 .

## 配置

此插件不需要配置 .

## 使用量

以下例子说明如何用已存在的密码来创建新的密码,认证,并检查设备上是否有密码.

### 创建新密码

注册用户账户的新密码 。 在真实的应用程序中, 选项必须由您的 WebAuthn 服务器提供, 结果必须返回到它进行验证 :

```typescript
import { Passkeys } from '@capawesome/capacitor-passkeys';

const createPasskey = async () => {
  // In a real app, the options must be provided by your WebAuthn server,
  // e.g. via `generateRegistrationOptions()` from SimpleWebAuthn.
  const result = await Passkeys.createPasskey({
    attestation: 'none',
    authenticatorSelection: {
      residentKey: 'required',
      userVerification: 'required',
    },
    challenge: 'dGhpc2lzYWNoYWxsZW5nZQ',
    pubKeyCredParams: [
      { alg: -7, type: 'public-key' },
      { alg: -257, type: 'public-key' },
    ],
    rp: { id: 'example.com', name: 'Example Inc.' },
    user: {
      displayName: 'Jane Doe',
      id: 'anVzdGFyYW5kb21pZA',
      name: 'jane.doe@example.com',
    },
  });
  // Pass the result to your WebAuthn server for verification,
  // e.g. via `verifyRegistrationResponse()` from SimpleWebAuthn.
  return result;
};
```

### 使用已有的密码认证

用先前为依赖方创建的密码在用户签名 。 再次, 选项来自您的 WebAuthn 服务器, 其结果由它验证 :

```typescript
import { Passkeys } from '@capawesome/capacitor-passkeys';

const getPasskey = async () => {
  // In a real app, the options must be provided by your WebAuthn server,
  // e.g. via `generateAuthenticationOptions()` from SimpleWebAuthn.
  const result = await Passkeys.getPasskey({
    challenge: 'dGhpc2lzYWNoYWxsZW5nZQ',
    rpId: 'example.com',
    userVerification: 'required',
  });
  // Pass the result to your WebAuthn server for verification,
  // e.g. via `verifyAuthenticationResponse()` from SimpleWebAuthn.
  return result;
};
```

### 检查是否有密码

在您的登录用户界面中提供密码之前, 请检查设备上是否有密码 。 在Android上,这个返回 `true` 如果设备运行Android 9(API 第28级)或更高。 在iOS上,它总是返回 `true`。在网络上,此返回 `true` 如果浏览器支持WebAuthn,并且有用户验证平台认证器:

```typescript
import { Passkeys } from '@capawesome/capacitor-passkeys';

const isAvailable = async () => {
  const { available } = await Passkeys.isAvailable();
  return available;
};
```

## API 密码

-   [`createPasskey(...)`](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-createpasskey)
-   [`getPasskey(...)`](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-getpasskey)
-   [`isAvailable()`](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-isavailable)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-type-aliases)

### 创建 Passkey (...)

```typescript
createPasskey(options: CreatePasskeyOptions) => Promise<CreatePasskeyResult>
```

创建( 注册) 新密码 .

选项映射 WebAuthn `PublicKeyCredentialCreationOptions` 贾森 串行化,以便任意 WebAuthn 服务器库提供的值 可以通过没有改变的通道.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CreatePasskeyOptions](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-createpasskeyoptions)` |

**回返情况:** `Promise<[CreatePasskeyResult](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-createpasskeyresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 获取 Passkey (...)

```typescript
getPasskey(options: GetPasskeyOptions) => Promise<GetPasskeyResult>
```

获取( 自动) 现有的密码 .

选项映射 WebAuthn `PublicKeyCredentialRequestOptions` 贾森 串行化,以便任意 WebAuthn 服务器库提供的值 可以通过没有改变的通道.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetPasskeyOptions](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-getpasskeyoptions)` |

**回返情况:** `Promise<[GetPasskeyResult](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-getpasskeyresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 易读 ()

```typescript
isAvailable() => Promise<IsAvailableResult>
```

检查此设备是否有密码 .

打开 **机器人**,这个返回 `true` 如果设备运行Android 9(API 第28级)或更高. 打开 **iOS系统**,它总是返回 `true`。 。 。 . 打开 **网页**,这个返回 `true` 如果浏览器支持WebAuthn和 有用户验证的平台认证器.

**回返情况:** `Promise<[IsAvailableResult](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-isavailableresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 创建 Passkey 结果

密码的创造结果.

此镜像 WebAuthn `RegistrationResponseJSON` 这样就可以了 转到任何 WebAuthn 服务器库进行校验.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`authenticatorAttachment`** | `[PasskeyAuthenticatorAttachment](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyauthenticatorattachment)` | 创建密码的验证器的附着. | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 证书标识符为 Base64url-encoded 字符串 . | 0.1.0 (中文(简体) ) |
| **`rawId`** | `string` | 原始证书标识符作为基数64url-编码字符串. | 0.1.0 (中文(简体) ) |
| **`response`** | `[CreatePasskeyResponse](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-createpasskeyresponse)` | 认证者的回应. | 0.1.0 (中文(简体) ) |
| **`type`** | `'public-key'` | 证书类型. | 0.1.0 (中文(简体) ) |

#### 创建 Passkey 响应

认证人关于办理新通行证注册的回复.

此镜像 WebAuthn `AuthenticatorAttestationResponse` 贾森 连载化.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`attestationObject`** | `string` | 证明对象为 Base64url-encoded 字符串 . | 0.1.0 (中文(简体) ) |
| **`authenticatorData`** | `string` | 认证器数据作为基础64url-encoded字符串. 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |
| **`clientDataJSON`** | `string` | 客户端数据作为base64url-encoded字符串. | 0.1.0 (中文(简体) ) |
| **`publicKey`** | `string` | DER-编码公钥作为 Base64url-编码字符串. 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |
| **`publicKeyAlgorithm`** | `number` | 公钥的 COSE 算法标识符 。 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |
| **`transports`** | `PasskeyTransport[]` | 认证者支持的传输. 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |

#### 创建 Passkey 选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`attestation`** | `[PasskeyAttestation](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyattestation)` | 证明传递偏好. | `'none'` | 0.1.0 (中文(简体) ) |
| **`authenticatorSelection`** | `[PasskeyAuthenticatorSelection](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyauthenticatorselection)` | 认证人必须达到的标准. |  | 0.1.0 (中文(简体) ) |
| **`challenge`** | `string` | 依赖方服务器作为base64url-encoded字符串提供的挑战. |  | 0.1.0 (中文(简体) ) |
| **`excludeCredentials`** | `PasskeyCredentialDescriptor[]` | 用户已经存在的证书,因此认证器不会为同一账户创建第二个密码. 打开 **iOS系统**,此选项仅适用于iOS 17.4 及以后. |  | 0.1.0 (中文(简体) ) |
| **`pubKeyCredParams`** | `PasskeyCredentialParameter[]` | 依赖方服务器支持的公钥证书类型和算法,从大多数到最低偏好订购. 仅在Android和Web上提供. |  | 0.1.0 (中文(简体) ) |
| **`rp`** | `[PasskeyRelyingParty](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyrelyingparty)` | 私钥创建的依赖方. |  | 0.1.0 (中文(简体) ) |
| **`timeout`** | `number` | 数以毫秒计的时间,呼叫者愿意等待操作完成. 仅在Android和Web上提供. |  | 0.1.0 (中文(简体) ) |
| **`user`** | `[PasskeyUser](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyuser)` | 密码创建的用户账户 . |  | 0.1.0 (中文(简体) ) |

#### 密码校正器选择

认证者必须满足的标准才能创建出密码.

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`authenticatorAttachment`** | `[PasskeyAuthenticatorAttachment](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyauthenticatorattachment)` | 认证器附件模式 。 仅在Android和Web上提供. |  | 0.1.0 (中文(简体) ) |
| **`requireResidentKey`** | `boolean` | 是否需要可发现证书( passkey) 。 此属性被保留用于与 WebAuthn 第 1 级的倒向兼容 。 偏爱 `residentKey`。只在Android和Web上提供. |  | 0.1.0 (中文(简体) ) |
| **`residentKey`** | `[PasskeyResidentKey](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyresidentkey)` | 依赖方希望创建可发现证书(passkey)的程度. 仅在Android和Web上提供. |  | 0.1.0 (中文(简体) ) |
| **`userVerification`** | `[PasskeyUserVerification](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyuserverification)` | 用户核查要求. | `'preferred'` | 0.1.0 (中文(简体) ) |

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

识别特定证书的描述符.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 证书标识符为 Base64url-encoded 字符串 . | 0.1.0 (中文(简体) ) |
| **`transports`** | `PasskeyTransport[]` | 证书认证人支持的传输. 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |
| **`type`** | `'public-key'` | 证书类型. | 0.1.0 (中文(简体) ) |

#### 通行证

依赖方的公钥证书类型和算法 服务器支持 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`alg`** | `number` | COSE算法标识符,例如. `-7` 用于ES256或 `-257` 编号为RS256. | 0.1.0 (中文(简体) ) |
| **`type`** | `'public-key'` | 证书类型. | 0.1.0 (中文(简体) ) |

#### 密码存储方

为谁创建了密码的依赖方.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 依赖方识别特征. 这必须是一个注册的域名后缀(或等于)该应用与之相关的域名. | 0.1.0 (中文(简体) ) |
| **`name`** | `string` | 依赖方的可人名. | 0.1.0 (中文(简体) ) |

#### 密码用户

创建密码的用户账户 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`displayName`** | `string` | 用户账户的可读显示名. | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 用户账户的用户手柄作为base64url-encoded字符串. | 0.1.0 (中文(简体) ) |
| **`name`** | `string` | 用户账户的可读名,例如用户名或电子邮件地址. | 0.1.0 (中文(简体) ) |

#### 获取 Passkey 结果

密码认证的结果.

此镜像 WebAuthn `AuthenticationResponseJSON` 这样就可以了 转到任何 WebAuthn 服务器库进行校验.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`authenticatorAttachment`** | `[PasskeyAuthenticatorAttachment](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyauthenticatorattachment)` | 提供密码的验证器的附着物. | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 证书标识符为 Base64url-encoded 字符串 . | 0.1.0 (中文(简体) ) |
| **`rawId`** | `string` | 原始证书标识符作为基数64url-编码字符串. | 0.1.0 (中文(简体) ) |
| **`response`** | `[GetPasskeyResponse](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-getpasskeyresponse)` | 认证者的回应. | 0.1.0 (中文(简体) ) |
| **`type`** | `'public-key'` | 证书类型. | 0.1.0 (中文(简体) ) |

#### 获取 Passkey 响应

认证人对认证的答复 现有密码.

此镜像 WebAuthn `AuthenticatorAssertionResponse` 贾森 连载化.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`authenticatorData`** | `string` | 认证器数据作为基础64url-encoded字符串. | 0.1.0 (中文(简体) ) |
| **`clientDataJSON`** | `string` | 客户端数据作为base64url-encoded字符串. | 0.1.0 (中文(简体) ) |
| **`signature`** | `string` | 签名为 Base64url- encoded 字符串 . | 0.1.0 (中文(简体) ) |
| **`userHandle`** | `string` | 用户手柄( `user.id` )作为碱基64url-编码字符串. | 0.1.0 (中文(简体) ) |

#### 获取 Passkey 选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`allowCredentials`** | `PasskeyCredentialDescriptor[]` | 依赖方服务器可接受的证书. 如果不提供,用户可以从依赖方的任何可发现的证书(passkey)中选择. |  | 0.1.0 (中文(简体) ) |
| **`challenge`** | `string` | 依赖方服务器作为base64url-encoded字符串提供的挑战. |  | 0.1.0 (中文(简体) ) |
| **`rpId`** | `string` | 依赖方识别特征. |  | 0.1.0 (中文(简体) ) |
| **`timeout`** | `number` | 数以毫秒计的时间,呼叫者愿意等待操作完成. 仅在Android和Web上提供. |  | 0.1.0 (中文(简体) ) |
| **`userVerification`** | `[PasskeyUserVerification](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-passkeyuserverification)` | 用户核查要求. | `'preferred'` | 0.1.0 (中文(简体) ) |

#### 易伤性结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`available`** | `boolean` | 此设备是否有密码可用 . | 0.1.0 (中文(简体) ) |

### 类型异名

#### 密码校正

认证器附件模式 .

`'cross-platform' | 'platform'`

#### 密码运输

认证人支持的运输工具.

`'ble' | 'hybrid' | 'internal' | 'nfc' | 'smart-card' | 'usb'`

#### 密码交换站

证明传递偏好.

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

#### 密码

依赖方希望在多大程度上 可发现证书( passkey).

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

#### 密码用户验证

用户核查要求.

-   `discouraged`:依赖方倾向于不进行用户验证.
-   `preferred`:依赖方倾向于用户验证,但将 没有它,操作就不会失败.
-   `required`:依赖方需要用户验证.

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

## 测试

在测试您的密码集成时, 请记住以下内容 :

-   **建议使用的真正设备**:在真设备上进行测试,设置了屏幕锁. 在iOS上,模拟器支持自iOS 16. 在Android上,模拟器需要Google Play服务并设置了谷歌密码管理器的Google账户.
-   **WebAuthn 服务器**: 此插件实例中的挑战只是占位符 。 在制作过程中,必须生成选项,结果必须由 WebAuthn 服务器库验证,例如 [简单WebAuthn](https://simplewebauthn.dev/) (节点.js)或 [java-webauthn 服务器](https://github.com/Yubico/java-webauthn-server) (贾瓦语).
-   **域协会**: 依赖方ID必须与您的应用程序相关(参见安装部分). 域关联变化需要一些时间来传播,因为文件被苹果和谷歌缓存.

## 限制

有条件的 UI( passkey 自动填充) 不支持此插件 。 操作系统自动填充集成以本地文本字段为目标,而不是网页视图中的HTML输入.

## 财务问题

### 此插件与其他类似插件有何不同?

它使用 JSON 序列化执行完整的WebAuthn 标准,所以任何WebAuthn 服务器库的选项和结果都会在Android,iOS,和Web上通过,没有改变. Passkey 创建、认证和 a `isAvailable()` 能力检查全部通过一个完全打字,积极维护的API进行. 如果您只需要本地的面部或指纹检查,简单的生物鉴别设置就足够了;如果您想要用服务器验证的密码来替换跨越每个平台的密码,这个插件就是为此设计的.

### 为什么插件方法会用 `DOMAIN_NOT_ASSOCIATED` 错误代码 ?

此错误意味着您的应用程序与依赖方的域无关( Name`rp.id` 编号 : `rpId`) (中文(简体) ). 在Android上,您必须托管数字资产链接文件 `https://<your-domain>/.well-known/assetlinks.json` 代表大会 `common.get_login_creds` 允许您的应用程序。 在iOS上,您必须添加关联域的能力与 `webcredentials` 服务类型和主机匹配 `apple-app-site-association` 文档。 见 [安装](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-installation) 详细情况。 还要记住,这些文件的更改可能需要一些时间来传播,因为它们被苹果和谷歌缓存.

### 我需要我自己的WebAuthn服务器来使用这个插件吗?

对 例子中显示的挑战只是占位符。 在生产中,选择 `createPasskey(...)` 财务报告和审定财务报表 `getPasskey(...)` 必须使用 WebAuthn 服务器生成,结果必须经过它验证,例如使用库,例如 [简单WebAuthn](https://simplewebauthn.dev/)。由于插件使用 WebAuthn JSON 序列化,任何WebAuthn 服务器库都未变.

### 哪些设备支持密码?

在Android上,Passkey在Android 9(API 第28级)上得到支持并更高,拥有Google密码管理器等可用的认证提供者. 在iOS上,在iOS 15上和上方支持密码. 在网络上,在使用用户验证平台认证器执行WebAuthn的浏览器中支持密码. 使用 `isAvailable()` 在运行时检查可用性的方法.

### 此插件是否支持密码自动填充( 有条件的 UI ) ?

不, 有条件的 UI 不支持 。 操作系统自动填充集成以本地文本字段为目标,而不是网页视图中的HTML输入. 见 [限制](https://npmcn.com/package/%40capawesome/capacitor-passkeys/#readme-limitations) 详细情况.

### 这个插件和生物测量插件有什么区别?

这个 [生物计量](https://capawesome.io/docs/sdks/capacitor/biometrics/) 插件在设备上执行本地生物鉴别检查(如面部或指纹识别),例如保护您应用中的屏幕. Passkeys插件执行WebAuthn标准,其中认证由您服务器加密验证,使其适合完全替换基于密码的登录.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [生物计量](https://capawesome.io/docs/sdks/capacitor/biometrics/):请求生物鉴别认证,如面部或指纹识别.
-   [奥奥特](https://capawesome.io/docs/sdks/capacitor/oauth/): 与OAuth 2.0和OpenID Connection 供应商通信.
-   [密码自动填充](https://capawesome.io/docs/sdks/capacitor/password-autofill/): 将密码保存到平台认证商店.
-   [安全优惠](https://capawesome.io/docs/sdks/capacitor/secure-preferences/):安全地存储密钥/值对,如密码或令牌等.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/passkeys/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/passkeys/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-passkeys 是什么？

在Android,iOS,和Web上创建并认证密码\(WebAuthn\)的电容插件\.

### 如何安装 @capawesome/capacitor-passkeys？

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

### @capawesome/capacitor-passkeys 支持 TypeScript 吗？

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

### @capawesome/capacitor-passkeys 支持 ESM 还是 CommonJS？

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

### @capawesome/capacitor-passkeys 可以商用吗？

@capawesome/capacitor-passkeys 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-passkeys 的下载量有多少？

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

### @capawesome/capacitor-passkeys 还在维护吗？

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