快速入门

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-firebase-authentication`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/firebase-authentication/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-firebase-authentication` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-firebase-authentication
npx cap sync

导入

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

快速入门

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.applyActionCode({ oobCode: 'oob-code' });

示例：confirmPasswordReset

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.confirmPasswordReset({
  oobCode: 'oob-code',
  newPassword: 'new-password',
});

示例：confirmVerificationCode

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.confirmVerificationCode({
  verificationId: 'phoneCodeSent',
  verificationCode: 'phoneCodeSent',
});
// The result holds sensitive values: use it without logging it.

常见坑点

监听器: 在页面卸载时移除句柄。
原生同步：运行 npx cap sync 在插件升级后。
唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

API 概览

`applyActionCode`

应用通过电子邮件发送给用户的验证 code。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.applyActionCode({ oobCode: 'oob-code' });

`confirmPasswordReset`

完成重置密码流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.confirmPasswordReset({
  oobCode: 'oob-code',
  newPassword: 'new-password',
});

`confirmVerificationCode`

完成手机号验证流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.confirmVerificationCode({
  verificationId: 'phoneCodeSent',
  verificationCode: 'phoneCodeSent',
});
// The result holds sensitive values: use it without logging it.

`createUserWithEmailAndPassword`

使用邮箱和密码创建新用户账号。如果账号创建成功，用户将自动登录。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.createUserWithEmailAndPassword({
  email: 'user@example.com',
  password: 'password',
});
// The result holds sensitive values: use it without logging it.

`deleteUser`

删除用户并退出登录。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.deleteUser();

`fetchSignInMethodsForEmail`

获取某个邮箱地址的登录方式。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.fetchSignInMethodsForEmail({ email: 'user@example.com' });
console.log(result);

`getCurrentUser`

获取当前已登录的用户。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getCurrentUser();
// The result holds sensitive values: use it without logging it.

`getPendingAuthResult`

返回 SignInResult 如果您的应用启动了 Web 登录流程，而操作系统在后台清理了该应用。

仅适用于 Android。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getPendingAuthResult();
// The result holds sensitive values: use it without logging it.

`getIdToken`

获取当前登录用户的 Firebase Auth ID Token。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getIdToken();
// The result holds sensitive values: use it without logging it.

`getIdTokenResult`

返回反序列化后的 JSON Web Token (JWT)，用于在 Firebase 服务中标识用户。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getIdTokenResult();
// The result holds sensitive values: use it without logging it.

`getRedirectResult`

返回 SignInResult （来自基于重定向的登录流程）。

如果登录失败，则会报错。如果未调用重定向操作，则返回一个 SignInResult 用户为 null。

仅 Web 端可用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getRedirectResult();
// The result holds sensitive values: use it without logging it.

`getTenantId`

获取租户 ID。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.getTenantId();
console.log(result);

`isSignInWithEmailLink`

检查传入链接是否为适用于……的电子邮件链接登录 signInWithEmailLink.

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.isSignInWithEmailLink({ emailLink: 'https://example.com' });
// The result holds sensitive values: use it without logging it.

`linkWithApple`

将用户账号与 Apple 身份验证提供商绑定。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithApple();
// The result holds sensitive values: use it without logging it.

`linkWithEmailAndPassword`

将用户账号与 Email 身份验证提供商绑定。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithEmailAndPassword({
  email: 'user@example.com',
  password: 'password',
});
// The result holds sensitive values: use it without logging it.

`linkWithEmailLink`

将用户账号与 Email 身份验证提供商绑定。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithEmailLink({
  email: 'user@example.com',
  emailLink: 'https://example.com',
});
// The result holds sensitive values: use it without logging it.

`linkWithFacebook`

将用户账号与 Facebook 身份验证提供商绑定。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithFacebook();
// The result holds sensitive values: use it without logging it.

`linkWithGameCenter`

将用户账号与 Game Center 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

仅 iOS 端可用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithGameCenter();
// The result holds sensitive values: use it without logging it.

`linkWithGithub`

将用户账号与 GitHub 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithGithub();
// The result holds sensitive values: use it without logging it.

`linkWithGoogle`

将用户账号与 Google 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithGoogle();
// The result holds sensitive values: use it without logging it.

`linkWithMicrosoft`

将用户账号与 Microsoft 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithMicrosoft();
// The result holds sensitive values: use it without logging it.

`linkWithOpenIdConnect`

将用户账号与 OpenID Connect 提供商关联。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithOpenIdConnect({ providerId: 'provider-id-123' });
// The result holds sensitive values: use it without logging it.

`linkWithPhoneNumber`

将用户账号与手机号身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

使用 phoneVerificationCompleted 验证完成时接收通知的监听器。使用 phoneVerificationFailed 验证失败时接收通知的监听器。使用 phoneCodeSent 用于获取验证 ID 的监听器。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.linkWithPhoneNumber({ phoneNumber: "+16505550101" });

`linkWithPlayGames`

将用户账号与 Play Games 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

仅适用于 Android。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithPlayGames();
// The result holds sensitive values: use it without logging it.

`linkWithTwitter`

将用户账号与 Twitter 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithTwitter();
// The result holds sensitive values: use it without logging it.

`linkWithYahoo`

将用户账号与 Yahoo 身份验证提供商关联。

用户必须已在原生层登录。该 skipNativeAuth 该配置选项在此处不起作用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.linkWithYahoo();
// The result holds sensitive values: use it without logging it.

`reload`

如果已登录，则重新加载用户账号数据。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.reload();

`revokeAccessToken`

撤销指定的 access token。目前仅支持 Apple OAuth access token。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.revokeAccessToken({ token: 'token-123' });

`sendEmailVerification`

向当前已登录用户发送验证邮件。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.sendEmailVerification();

`sendPasswordResetEmail`

发送密码重置邮件。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.sendPasswordResetEmail({ email: 'user@example.com' });

`sendSignInLinkToEmail`

向指定邮箱的用户发送登录邮件链接。

若要通过邮件链接完成登录，请调用 signInWithEmailLink 并传入用户收到的邮件中的邮箱地址和邮件链接。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.sendSignInLinkToEmail({
  email: 'user@example.com',
  actionCodeSettings: { url: 'https://example.com' },
});

`setLanguageCode`

设置身份验证操作面向用户的语言 code。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.setLanguageCode({ languageCode: "en-US" });

`setPersistence`

设置当前已保存的身份验证会话的持久化类型。

仅 Web 端可用。

import { FirebaseAuthentication, Persistence } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.setPersistence({ persistence: Persistence.IndexedDbLocal });

`setTenantId`

设置租户 ID。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.setTenantId({ tenantId: 'tenant-id-123' });

`signInAnonymously`

以匿名用户身份登录。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInAnonymously();
// The result holds sensitive values: use it without logging it.

`signInWithApple`

启动 Apple 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithApple();
// The result holds sensitive values: use it without logging it.

`signInWithCustomToken`

启动 Custom Token 登录流程。

此方法不能与以下内容结合使用： skipNativeAuth 在 Android 和 iOS 上。在这种情况下，你必须直接使用 signInWithCustomToken Firebase JS SDK 的 interface。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithCustomToken({ token: 'token-123' });
// The result holds sensitive values: use it without logging it.

`signInWithEmailAndPassword`

启动邮箱和密码登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithEmailAndPassword({
  email: 'user@example.com',
  password: 'password',
});
// The result holds sensitive values: use it without logging it.

`signInWithEmailLink`

使用邮箱和登录邮件链接登录。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithEmailLink({
  email: 'user@example.com',
  emailLink: 'https://example.com',
});
// The result holds sensitive values: use it without logging it.

`signInWithFacebook`

启动 Facebook 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithFacebook();
// The result holds sensitive values: use it without logging it.

`signInWithGameCenter`

启动 Game Center 登录流程。

仅限 iOS 使用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithGameCenter();
// The result holds sensitive values: use it without logging it.

`signInWithGithub`

启动 GitHub 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithGithub();
// The result holds sensitive values: use it without logging it.

`signInWithGoogle`

启动 Google 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithGoogle();
// The result holds sensitive values: use it without logging it.

`signInWithMicrosoft`

启动 Microsoft 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithMicrosoft();
// The result holds sensitive values: use it without logging it.

`signInWithOpenIdConnect`

启动 OpenID Connect 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithOpenIdConnect({ providerId: 'provider-id-123' });
// The result holds sensitive values: use it without logging it.

`signInWithPhoneNumber`

启动使用手机号的登录流程。

仅适用于 Android 和 iOS。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.signInWithPhoneNumber({ phoneNumber: "+16505550101" });

`signInWithPlayGames`

启动 Play Games 登录流程。

仅适用于 Android。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithPlayGames();
// The result holds sensitive values: use it without logging it.

`signInWithTwitter`

启动 Twitter 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithTwitter();
// The result holds sensitive values: use it without logging it.

`signInWithYahoo`

启动 Yahoo 登录流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.signInWithYahoo();
// The result holds sensitive values: use it without logging it.

`signOut`

启动登出流程。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.signOut();

`unlink`

从用户账号中解绑身份提供商。

import { FirebaseAuthentication, ProviderId } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.unlink({ providerId: ProviderId.APPLE });
// The result holds sensitive values: use it without logging it.

`updateEmail`

更新当前登录用户的邮箱地址。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.updateEmail({ newEmail: 'user@example.com' });

`updatePassword`

更新当前已登录用户的密码。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.updatePassword({ newPassword: 'new-password' });

`updateProfile`

更新用户个人资料数据。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.updateProfile({
  displayName: 'display',
  photoUrl: 'https://example.com',
});

`useAppLanguage`

将面向用户的语言 code 设置为应用的默认语言。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.useAppLanguage();

`useEmulator`

配置应用以连接 Authentication 模拟器。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.useEmulator({ host: "127.0.0.1" });

`verifyBeforeUpdateEmail`

先验证新邮箱地址，再更新当前登录用户的邮箱地址。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

await FirebaseAuthentication.verifyBeforeUpdateEmail({ newEmail: 'user@example.com' });

`checkAppTrackingTransparencyPermission`

检查应用追踪透明度（App Tracking Transparency）的当前状态。

仅 iOS 端可用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.checkAppTrackingTransparencyPermission();
console.log(result);

`requestAppTrackingTransparencyPermission`

打开系统对话框以授权应用追踪透明度。

注意： 用户可能已在设备设置中禁用了追踪请求，请参阅 Apple 官方文档.

仅限 iOS 使用。

import { FirebaseAuthentication } from '@capgo/capacitor-firebase-authentication';

const result = await FirebaseAuthentication.requestAppTrackingTransparencyPermission();
console.log(result);

类型参考

`ApplyActionCodeOptions`

export interface ApplyActionCodeOptions {
  /**
   * A verification code sent to the user.
   *
   * @since 0.2.2
   */
  oobCode: string;
}

`ConfirmPasswordResetOptions`

export interface ConfirmPasswordResetOptions {
  /**
   * A verification code sent to the user.
   *
   * @since 0.2.2
   */
  oobCode: string;
  /**
   * The new password.
   *
   * @since 0.2.2
   */
  newPassword: string;
}

`ConfirmVerificationCodeOptions`

export interface ConfirmVerificationCodeOptions {
  /**
   * The verification ID received from the `phoneCodeSent` listener.
   *
   * The `verificationCode` option must also be provided.
   *
   * @since 5.0.0
   */
  verificationId: string;
  /**
   * The verification code either received from the `phoneCodeSent` listener or entered by the user.
   *
   * The `verificationId` option must also be provided.
   *
   * @since 5.0.0
   */
  verificationCode: string;
}

`SignInResult`

export interface SignInResult {
  /**
   * The currently signed-in user, or null if there isn't any.
   *
   * @since 0.1.0
   */
  user: User | null;
  /**
   * Credentials returned by an auth provider.
   *
   * @since 0.1.0
   */
  credential: AuthCredential | null;
  /**
   * Additional user information from a federated identity provider.
   *
   * @since 0.5.1
   */
  additionalUserInfo: AdditionalUserInfo | null;
}

`CreateUserWithEmailAndPasswordOptions`

export interface CreateUserWithEmailAndPasswordOptions {
  /**
   * @since 0.2.2
   */
  email: string;
  /**
   * @since 0.2.2
   */
  password: string;
}

`FetchSignInMethodsForEmailOptions`

export interface FetchSignInMethodsForEmailOptions {
  /**
   * The user's email address.
   *
   * @since 6.0.0
   */
  email: string;
}

`FetchSignInMethodsForEmailResult`

export interface FetchSignInMethodsForEmailResult {
  /**
   * The sign-in methods for the specified email address.
   *
   * This list is empty when [Email Enumeration Protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection)
   * is enabled, irrespective of the number of authentication methods available for the given email.
   *
   * @since 6.0.0
   */
  signInMethods: string[];
}

`GetCurrentUserResult`

export interface GetCurrentUserResult {
  /**
   * The currently signed-in user, or null if there isn't any.
   *
   * @since 0.1.0
   */
  user: User | null;
}

`GetIdTokenOptions`

export interface GetIdTokenOptions {
  /**
   * Force refresh regardless of token expiration.
   *
   * @since 0.1.0
   */
  forceRefresh: boolean;
}

`GetIdTokenResult`

export interface GetIdTokenResult {
  /**
   * The Firebase Auth ID token JWT string.
   *
   * @since 0.1.0
   */
  token: string;
}

`GetIdTokenResultOptions`

export interface GetIdTokenResultOptions {
  /**
   * Force refresh regardless of token expiration.
   *
   * @since 7.4.0
   */
  forceRefresh: boolean;
}

`GetIdTokenResultResult`

export interface GetIdTokenResultResult {
  /**
   * The authentication time in milliseconds since the epoch.
   *
   * This is the time the user authenticated (signed in) and not the time the token was refreshed.
   *
   * @since 7.4.0
   */
  authTime: number;
  /**
   * The ID token expiration time in milliseconds since the epoch.
   *
   * @since 7.4.0
   */
  expirationTime: number;
  /**
   * The ID token issuance time in milliseconds since the epoch.
   *
   * @since 7.4.0
   */
  issuedAtTime: number;
  /**
   * The sign-in provider through which the ID token was obtained.
   *
   * @since 7.4.0
   */
  signInProvider: string | null;
  /**
   * The type of second factor associated with this session, provided the user was multi-factor
   * authenticated (eg. phone, etc).
   *
   * @since 7.4.0
   */
  signInSecondFactor: string | null;
  /**
   * The entire payload claims of the ID token including the standard reserved claims as well as
   * the custom claims.
   *
   * @since 7.4.0
   */
  claims: Record<string, unknown>;
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 用来规划身份验证和账户流程，并将它与 @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 有关 @capgo/capacitor-native-biometric 的实现细节，双因素认证有关双因素认证的实现细节，以及 SSO (企业版) 有关 SSO (Enterprise) 的实现细节。