# @farcaster/auth-kit 中文文档

规范地址：https://npmcn.com/package/%40farcaster/auth-kit/

版本：0\.8\.2
npm 元数据更新时间：2026-10-26T13:54:45.598Z
中文译文更新时间：2026-11-14T10:12:33.678Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40farcaster/auth-kit
原文对照：https://npmcn.com/package/%40farcaster/auth-kit/?lang=original
项目主页：https://github.com/farcasterxyz/auth-monorepo#readme
源码仓库：https://github.com/farcasterxyz/auth-monorepo

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

- 包体积（解压后）：99.8 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react \>= 17，react-dom \>= 17
- 首次发布：2024-01-11T17:08:40.729Z
- 最新版本发布：2026-02-05T00:23:01.937Z
- 近 30 天下载量：24629（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 5 个）

## 中文简介

一个反应库,可以方便地将Sign In With Farcaster添加到您的应用程序中.

## 安装

```sh
npm install @farcaster/auth-kit
```

也可以使用：`pnpm add @farcaster/auth-kit`、`yarn add @farcaster/auth-kit`、`bun add @farcaster/auth-kit`

## README

# `@farcaster/auth-kit`

一个反应库,可以方便地将Sign In With Farcaster添加到您的应用程序中.

## 开始

### 安装

安装 AuthKit 及其对等依赖 [维姆](https://viem.sh/)。 。 。 .

```sh
npm install @farcaster/auth-kit viem
```

**说明:** AuthKit 是一个 [反应](https://reactjs.org/) 图书馆。 如果你使用另一个前端框架,请看看 [`@farcaster/auth-client`](https://npmcn.com/package/%40farcaster/auth-client/) 图书馆.

### 导入

导入样式和函数 .

```tsx
import "@farcaster/auth-kit/styles.css";
import { AuthKitProvider } from "@farcaster/auth-kit";
```

### 添加提供者

用 `AuthKitProvider`。 。 。 .

```tsx
const config = {
  // For a production app, replace this with an Optimism Mainnet
  // RPC URL from a provider like Alchemy or Infura.
  rpcUrl: "https://mainnet.optimism.io",
  domain: "example.com",
  siweUri: "https://example.com/login",
};

const App = () => {
  return <AuthKitProvider config={config}>{/* Your App */}</AuthKitProvider>;
};
```

## 在按钮中添加标志

然后,在你的应用中,导入和渲染 `SignInButton` 组件.

```tsx
import { SignInButton } from "@farcaster/auth-kit";

export const SignIn = ({ nonce }: { nonce: string }) => {
  return <SignInButton nonce={nonce} />;
};
```

法克斯特按钮的标志将会生效 当用户点击时,他们会被提示在使用他们的Farcaster钱包应用程序时完成签名. 一旦他们完成签名 在签名消息中 将返回回召.

## 实例

您可以找到正式的例子 [这里](https://github.com/farcasterxyz/connect-monorepo/tree/main/examples)。 。 。 .

## 解决问题

使用的项目 [创建反应 App( CRA)](https://create-react-app.dev/) 可能遇到 TypeScript 版本冲突, 如 `react-scripts@5.0.1` 期望 TypeScript 版本的对等依赖 `^3.2.1 || ^4`,而viem和AuthKit都要求 `>=5.0.4`。 。 。 .

为解决这一问题:

-   安装 TypeScript 的最新版本 : `npm i typescript -D`
-   添加覆盖 `react-scripts` 要删除版本天花板 :

```json
"overrides": {
  "react-scripts": {
    "typescript": ">3.2.1"
  }
}
```

**说明**: 始终小心地处理超接,并确保它们与使用它们的包兼容.

## 构成部分

### `AuthKitProvider`

将您的申请包成 `AuthKitProvider` 以使用法克斯特·奥特.

```tsx
const config = {
  domain: "example.com",
  siweUri: "https://example.com/login",
  rpcUrl: "https://mainnet.optimism.io",
  relay: "https://relay.farcaster.xyz",
};

const App = () => {
  return <AuthKitProvider config={config}>{/* Your App */}</AuthKitProvider>;
};
```

#### 道具

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `config` | `AuthKitConfig` | 对 | 配置对象 。 见下表. |

`config` 选项:

| 参数 | 类型 | 需求 | 说明 | 默认 |
| --- | --- | --- | --- | --- |
| `domain` | `string` | 对 | 您的应用程序域 . | 无 |
| `siweUri` | `string` | 对 | 一个URI识别您的申请. | 无 |
| `relay` | `string` | 没有 | Farcaster Auth 中继服务器 URL | `https://relay.farcaster.xyz` |
| `rpcUrl` | `string` | 没有 | 优化 RPC 服务器 URL | `https://mainnet.optimism.io` |
| `version` | `string` | 没有 | 法克斯特奥特版本 | `v1` |

### `SignInButton`

主要内容。 将"Sign in With Farcaster"按钮渲染出,该按钮会促使用户用手机在网络上扫描QR代码,或者直接在移动设备上重定向. 您可以使用回调道具或钩子访问用户的认证状态和配置信息.

```tsx
import { SignInButton } from "@farcaster/auth-kit";

export const SignIn = ({ nonce }: { nonce: string }) => {
  return (
    <SignInButton
      nonce={nonce}
      onSuccess={({ fid, username }) =>
        console.log(`Hello, ${username}! Your fid is ${fid}.`)
      }
    />
  );
};
```

#### 道具

| Prop | 类型 | 需求 | 说明 | 默认 |
| --- | --- | --- | --- | --- |
| `timeout` | `number` | 没有 | 中继服务器超时( ms) . | `300000` (5分钟) |
| `interval` | `number` | 没有 | 中继服务器投票间隔以毫秒计. | `1500` (1.5秒钟) |
| `nonce` | `string` | 没有 | 随机非ce 将包含在 Sign In With Farcaster 信件中 . | 无 |
| `notBefore` | `string` | 没有 | SIWF 消息生效的时间 。 ISO 8601 日期时间字符串. | 无 |
| `expirationTime` | `string` | 没有 | SIWF消息到期时间 。 ISO 8601 日期时间字符串. | 无 |
| `requestId` | `string` | 没有 | 包含在SIWF消息中的可选系统特定ID. | 无 |
| `onSuccess` | `(res: UseSignInData) => void` | 没有 | 在签名完成且用户被认证时引用回调 . | 无 |
| `onStatusResponse` | `(res: UseWatchStatusData) => void` | 没有 | 当组件从中继服务器收到状态更新时引用回调 . | 无 |
| `onError` | `(error: AuthClientError) => void` | 没有 | 错误调用函数 . | 无 |
| `debug` | `boolean` | 没有 | 渲染显示内部 AuthKit 状态的调试面板 . | `false` |

## 钩子

### `useSignIn`

钩在用户签名。 连接到中继服务器,生成QR代码并签名链接到用户面前,投票中继服务器进行钱包签名.

```tsx
import { QRCode, useSignIn } from "@farcaster/auth-kit";

function App() {
  const {
    signIn,
    url
    data: { username },
    onSuccess: ({ fid }) => console.log("Your fid:", fid);
  } = useSignIn();

  return (
    <div>
      <button onClick={signIn}>Sign In</button>
      {qrCodeUri && (
        <span>
          Scan this: <QRCode uri={url} />
        </span>
      )}
      {username && `Hello, ${username}!`}
    </div>
  );
}
```

#### 参数

| 参数 | 类型 | 需求 | 说明 | 默认 |
| --- | --- | --- | --- | --- |
| `timeout` | `number` | 没有 | 中继服务器超时( ms) . | `300000` (5分钟) |
| `interval` | `number` | 没有 | 中继服务器投票间隔以毫秒计. | `1500` (1.5秒钟) |
| `nonce` | `string` | 没有 | 随机非ce 将包含在 Sign In With Farcaster 信件中 . | 无 |
| `notBefore` | `string` | 没有 | SIWF 消息生效的时间 。 ISO 8601 日期时间字符串. | 无 |
| `expirationTime` | `string` | 没有 | SIWF消息到期时间 。 ISO 8601 日期时间字符串. | 无 |
| `requestId` | `string` | 没有 | 包含在SIWF消息中的可选系统特定ID. | 无 |
| `onSuccess` | `(res: UseSignInData) => void` | 没有 | 在签名完成且用户被认证时引用回调 . | 无 |
| `onStatusResponse` | `(res: UseWatchStatusData) => void` | 没有 | 当组件从中继服务器收到状态更新时引用回调 . | 无 |
| `onError` | `(error: AuthClientError) => void` | 没有 | 错误调用函数 . | 无 |

#### 回返

```ts
  {
    signIn: () => void;
    reconnect: () => void;
    isSuccess: boolean;
    isPolling: boolean;
    isError: boolean;
    error: AuthClientError;
    channelToken: string;
    url: string;
    qrCodeUri: string;
    data: {
        state: "pending" | "complete";
        nonce: string;
        message: string;
        signature: string;
        fid: number;
        username: string;
        bio: string;
        displayName: string;
        pfpUrl: string;
        custody: Hex;
        verifications: Hex[];
    },
    validSignature: boolean;
  };
```

| 参数 | 说明 |
| --- | --- |
| `signIn` | 调用此函数可连接到中继器并进行民意测验以获取签名. |
| `reconnect` | 再接接接接接接接接接接接接接 出错时使用 . |
| `isSuccess` | 中继服务器返回有效签名时为真 . |
| `isPolling` | 中继状态为真 `"pending"` 应用正在投票给中继服务器以获取响应. |
| `isError` | 出错时为真 . |
| `error` | `AuthClientError` 举个例子. |
| `channelToken` | Farcaster Auth中继频道代号. |
| `url` | 在 Farcaster URL 中签名以提交用户 。 v1中与Wrpcast的链接. |
| `qrcodeUri` | QR 代码图像数据 URI 编码 `url`。 。 。 . |
| `data.state` | 请求中的标志状况 `"pending"` 或者说 `"complete"` |
| `data.nonce` | SIWE 信件中使用的随机非ce 。 如果您不提供自定义非ce,请读取此值. |
| `data.message` | 生成的 SIWE 消息 . |
| `data.signature` | 由用户的Wrpcast钱包所制作的Hex签名. |
| `data.fid` | 用户法克斯特ID. |
| `data.username` | 用户法克斯特用户名. |
| `data.bio` | 用户法克斯特生物. |
| `data.displayName` | 用户法克斯特显示名. |
| `data.pfpUrl` | 用户的"Farcaster"简介图片URL. |
| `data.custody` | 用户的Farcaster身份证保管地址. |
| `data.verifications` | 用户核实的地址. |
| `validSignature` | 中继服务器返回的签名有效时为真 . |

### `useProfile`

读取认证用户信息的钩子 .

```tsx
import { useProfile } from "@farcaster/auth-kit";

function App() {
  const {
    isAuthenticated,
    profile: { fid, pfpUrl, username, displayName, bio },
  } = useProfile();

  return (
    <div>
     { isAuthenticated ? <p>Hello, {username}! Your fid is {fid}.<p>  : <p>You're not signed in.</p>}
    </div>
  );
}
```

#### 回返

```ts
  {
    isAuthenticated: boolean;
    profile: {
        fid: number;
        username: string;
        bio: string;
        displayName: string;
        pfpUrl: string;
    },
  };
```

| 参数 | 说明 |
| --- | --- |
| `isAuthenticated` | 如果用户被认证为真 . |
| `profile.fid` | 用户法克斯特ID. |
| `profile.username` | 用户法克斯特用户名. |
| `profile.bio` | 用户法克斯特生物. |
| `profile.displayName` | 用户法克斯特显示名. |
| `profile.pfpUrl` | 用户的"Farcaster"简介图片URL. |
| `profile.custody` | 用户的Farcaster身份证保管地址. |
| `profile.verifications` | 用户核实的地址. |

### `useSignInMessage`

用于读取用于认证用户的SIWE消息和签名的Hook.

```tsx
import { useSignInMessage } from "@farcaster/auth-kit";

function App() {
  const { message, signature } = useSignInMessage();

  return (
    <div>
      <p>You signed: {message}</p>
      <p>Your signature: {signature}</p>
    </div>
  );
}
```

#### 回返

```ts
{
  message: string;
  signature: string;
}
```

| 参数 | 说明 |
| --- | --- |
| `message` | SIWE消息由用户签名. |
| `signature` | 由用户Warpcast钱包制作的签名. |

## 常见问题

### @farcaster/auth-kit 是什么？

一个反应库,可以方便地将Sign In With Farcaster添加到您的应用程序中\.

### 如何安装 @farcaster/auth-kit？

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

### @farcaster/auth-kit 支持 TypeScript 吗？

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

### @farcaster/auth-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @farcaster/auth-kit 可以商用吗？

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

### @farcaster/auth-kit 的下载量有多少？

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

### @farcaster/auth-kit 还在维护吗？

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