# @convex-dev/workos-authkit 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/workos-authkit/

版本：0\.3\.0
npm 元数据更新时间：2026-10-28T05:57:17.468Z
中文译文更新时间：2026-11-10T17:46:55.982Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/workos-authkit
原文对照：https://npmcn.com/package/%40convex-dev/workos-authkit/?lang=original
项目主页：https://github.com/get-convex/workos-authkit#readme
源码仓库：https://github.com/get-convex/workos-authkit

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

- 包体积（解压后）：178 kB，73 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.29\.3，@workos-inc/node ^7\.75\.1 \|\| ^8\.0\.0 \|\| ^9\.0\.0 \|\| ^10\.0\.0，@workos-inc/authkit-react ^0\.13\.0 \|\| ^0\.16\.0
- 首次发布：2025-11-27T17:27:32.424Z
- 最新版本发布：2026-10-28T05:57:17.259Z
- 近 30 天下载量：292851（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Convex 的 WorkOS AuthKit 组件 .

## 安装

```sh
npm install @convex-dev/workos-authkit
```

也可以使用：`pnpm add @convex-dev/workos-authkit`、`yarn add @convex-dev/workos-authkit`、`bun add @convex-dev/workos-authkit`

## README

# Convex 工作OS AuthKit 系统

[![npm version](https://badge.fury.io/js/@convex-dev%2Fworkos-authkit.svg?)](https://badge.fury.io/js/@convex-dev%2Fworkos-authkit)

此组件是将 WorkOS AuthKit 认证与您的 Convex 项目整合的正式方式 .

特征 :

-   将用户数据从 WorkOS 同步到您的 Convex 数据库 可靠且持久 .
-   响应带有 Convex 函数的事件 .
-   将组件添加到现有应用程序时回填已存在的 WorkOS 用户 .

见 [实例](https://npmcn.com/package/%40convex-dev/workos-authkit/example) 用于演示如何将此组件纳入您的应用程序.

打开 a [GitHub 问题](https://github.com/get-convex/workos-authkit/issues) 与 任何反馈或错误.

## 先决条件

跟着 [Convex 工作OS AuthKit 引导](https://docs.convex.dev/auth/authkit/) 与WorkOS AuthKit一起建立一个工作项目.

然后遵循下面的步骤来设置用户数据同步和事件处理.

## 配置网点

用户数据同步需要在您的 WorkOS 项目中配置webhooks .

在 WorkOS 工程中从左侧栏选择 Webhooks, 并创建新 以下设置的 webhook :

-   **端点 URL**数字 : `https://<your-convex-deployment>.convex.site/workos/webhook`
-   **活动**数字 : `user.created`, (中文(简体) ), `user.updated`, (中文(简体) ), `user.deleted`

![Webhook configuration](https://raw.githubusercontent.com/get-convex/workos-authkit/refs/heads/main/assets/webhook-configuration.png)

复制 Webhook 密钥并将其添加到您的环境变量中 `WORKOS_WEBHOOK_SECRET`。 。 。 . ![Webhook header](https://raw.githubusercontent.com/get-convex/workos-authkit/refs/heads/main/assets/webhook-header.png)

```sh
npx convex env set WORKOS_WEBHOOK_SECRET=<your-webhook-secret>
```

## 安装

第一,添加 `@convex-dev/workos-authkit` 到您的 Convex 项目 :

```sh
npm install @convex-dev/workos-authkit
```

然后在您内部安装组件 `convex/convex.config.ts` 文件 :

```ts
// convex/convex.config.ts
import workOSAuthKit from "@convex-dev/workos-authkit/convex.config";
import { defineApp } from "convex/server";

const app = defineApp();
app.use(workOSAuthKit);
export default app;
```

在您内部创建 Convex AuthKit 客户端 `convex/` 文件夹,并指向 至已安装组件:

```ts
// convex/auth.ts
import { AuthKit } from "@convex-dev/workos-authkit";
import { components } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

export const authKit = new AuthKit<DataModel>(components.workOSAuthKit);
```

最后,在 `convex/http.ts`数字 :

```ts
import { httpRouter } from "convex/server";
import { authKit } from "./auth";

const http = httpRouter();
authKit.registerRoutes(http);
export default http;
```

## 自定义域

如果你已经配置了 [自定义 WorkOS 认证 API 域](https://workos.com/docs/custom-domains/auth-api),通过它作为 `apiHostname` 当构建 AuthKit 客户端时。 它将 WorkOS SDK 通过您的域名并更新 JWT 发行器和 JWKS URL 以匹配 .

```ts
// convex/auth.ts
export const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  apiHostname: "auth.example.com",
});
```

## 使用量

WorkOS中的用户创建/更新/删除会自动被同步 组件.

使用 `getAuthUser` 获取当前认证用户的组件方法 对象 :

```ts
export const getCurrentUser = query({
  args: {},
  handler: async (ctx, _args) => {
    const user = await authKit.getAuthUser(ctx);
    return user;
  },
});
```

## 活动

AuthKit 组件可以配置用于处理来自 WorkOS 的事件. 这是 用于在 WorkOS 中创建、更新或删除用户时运行代码, 或针对任何其他提供的事件.

默认情况下,该组件将处理以下事件:

-   `user.created`
-   `user.updated`
-   `user.deleted`

这个 `user.deleted` 当组件从未存储用户时, 处理器也会运行, for 例如WorkOS在创建前发送删除. `event.data` 那时 已发送的 webhook 有效载荷,所以 `id` 虽然它被打成 一个完整的用户。 当组件存储了用户时,其字段会填补任何空白.

**如果您的应用程序没有用户记录, 请务必返回而不是丢弃 .** 扔出失败的 Webhook 并滚回组件的删除记录, 这样 `user.created` 在 WorkOS 重试之前到达的 组件和您的应用程序.

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

// Get a typed object of internal Convex functions exported by this file
const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

// create `authKitEvent` as a named export
export const { authKitEvent } = authKit.events({
  "user.created": async (ctx, event) => {
    // ctx is a mutation context and event.data is typed
    await ctx.db.insert("todoLists", {
      name: `${event.data.firstName}'s Todo List`,
      userId: event.data.id,
    });
  },
});
```

### 其他事件类型

该组件可以处理任意WorkOS事件类型. WorkOS文件提供a [完整 事件列表](https://workos.com/docs/events)。处理额外事件 类型,请在 [webhook 配置](https://npmcn.com/package/%40convex-dev/workos-authkit/#readme-configure-webhooks) 添加一个 处理者.

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

export const { authKitEvent } = authKit.events({
  "session.created": async (ctx, event) => {
    // do something with the session data
  },
  "session.revoked": async (ctx, event) => {
    // do something with the session data
  },
});
```

## 用户数据

大多数应用程序需要控制其用户计划,并能直接查询 与用户表相对。 AuthKit 组件拥有自己的用户表和用户 数据来自WorkOS. 您可以将此视为用户的认证元数据, 但是 您可能想要通过您的应用程序中的额外数据来扩展此功能 .

常见的模式是创建自己的用户表,其中参考 authKit 用户表,使用用户事件进行任何必要的同步.

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

export const { authKitEvent } = authKit.events({
  "user.created": async (ctx, event) => {
    await ctx.db.insert("users", {
      authId: event.data.id,
      email: event.data.email,
      name: `${event.data.firstName} ${event.data.lastName}`,
    });
  },
  "user.updated": async (ctx, event) => {
    const user = await ctx.db
      .query("users")
      .withIndex("authId", (q) => q.eq("authId", event.data.id))
      .unique();
    if (!user) {
      console.warn(`User not found: ${event.data.id}`);
      return;
    }
    await ctx.db.patch(user._id, {
      email: event.data.email,
      name: `${event.data.firstName} ${event.data.lastName}`,
    });
  },
  "user.deleted": async (ctx, event) => {
    const user = await ctx.db
      .query("users")
      .withIndex("authId", (q) => q.eq("authId", event.data.id))
      .unique();
    if (!user) {
      console.warn(`User not found: ${event.data.id}`);
      return;
    }
    await ctx.db.delete(user._id);
  },

  // Handle any event type
  "session.created": async (ctx, event) => {
    console.log("onCreateSession", event);
  },
});
```

## 回填现有用户

如果您正在将此组件添加到一个已经在 WorkOS 有用户的应用程序中, 您 可以将它们回填入组件的用户表。 后面的填充物也会起火 `user.created` 事件处理器,所以你的应用程序自己的表格也会有人.

从您的认证文件导出回填工具 :

```ts
// convex/auth.ts
export const { backfillUsers } = authKit.utils();
```

然后从CLI或Convex仪表板触发:

```sh
npx convex run auth:backfillUsers
```

回填处理用户最老-最先. 这是天分 - 如果中断,只是 它会跳过已经同步的用户 .

## 行动

AuthKit 组件可以配置用于处理来自 WorkOS 的动作. 行动 允许您根据自己的逻辑屏蔽用户注册或认证. 更多信息,请访问 [工作操作系统 文档](https://workos.com/docs/authkit/actions)。 。 。 .

## 配置

1.  在工作OS仪表板中配置动作 .
2.  设置您动作的终点 URL `https://<your-convex-deployment>.convex.site/workos/action`
3.  从仪表盘上复制动作签名秘诀,放入您 环境变量为 `WORKOS_ACTION_SECRET`。 。 。 .

![Action configuration](https://raw.githubusercontent.com/get-convex/workos-authkit/refs/heads/main/assets/action-configuration.png)

## 使用量

动作处理器使用 `actions` authKit 组件上的方法. AuthKit 动作必须返回允许或否认该动作的响应有效载荷, 因此向动作处理器提供了响应对象 `allow` 财务报告和审定财务报表 `deny` 方法。 。 .

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

export const { authKitAction } = authKit.actions({
  authentication: async (_ctx, _action, response) => {
    return response.allow();
  },
  userRegistration: async (_ctx, action, response) => {
    if (action.userData.email.endsWith("@gmail.com")) {
      return response.deny("Gmail accounts are not allowed");
    }
    return response.allow();
  },
});
```

## 常见问题

### @convex-dev/workos-authkit 是什么？

Convex 的 WorkOS AuthKit 组件 \.

### 如何安装 @convex-dev/workos-authkit？

在项目目录运行 npm install @convex-dev/workos-authkit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.29\.3）、@workos-inc/node（^7\.75\.1 \|\| ^8\.0\.0 \|\| ^9\.0\.0 \|\| ^10\.0\.0）、@workos-inc/authkit-react（^0\.13\.0 \|\| ^0\.16\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/workos-authkit 支持 TypeScript 吗？

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

### @convex-dev/workos-authkit 支持 ESM 还是 CommonJS？

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

### @convex-dev/workos-authkit 可以商用吗？

@convex-dev/workos-authkit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/workos-authkit 的下载量有多少？

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

### @convex-dev/workos-authkit 还在维护吗？

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