# @clerk/electron 中文文档

规范地址：https://npmcn.com/package/%40clerk/electron/

版本：0\.1\.13
npm 元数据更新时间：2026-11-17T00:14:35.855Z
中文译文更新时间：2026-11-17T00:17:02.791Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clerk/electron
原文对照：https://npmcn.com/package/%40clerk/electron/?lang=original
项目主页：https://clerk.com/
源码仓库：https://github.com/clerk/javascript

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

- 包体积（解压后）：284 kB，67 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.9\.0
- 运行依赖：3 个
- peer 依赖：react ^18\.0\.0 \|\| ~19\.0\.3 \|\| ~19\.1\.4 \|\| ~19\.2\.3 \|\| ~19\.3\.0-0，electron \>=28，react-dom ^18\.0\.0 \|\| ~19\.0\.3 \|\| ~19\.1\.4 \|\| ~19\.2\.3 \|\| ~19\.3\.0-0，electron-store ^8\.2\.0，@clerk/electron-passkeys \*
- 首次发布：2026-06-15T15:33:41.404Z
- 最新版本发布：2026-11-17T00:14:35.474Z
- 近 30 天下载量：476296（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：1278（近 12 个月 1278 个）

## 中文简介

电子的办事员 SDK

## 安装

```sh
npm install @clerk/electron
```

也可以使用：`pnpm add @clerk/electron`、`yarn add @clerk/electron`、`bun add @clerk/electron`

## README

[![](https://images.clerk.com/static/logo-light-mode-400x400.png)](https://clerk.com/?utm_source=github&utm_medium=clerk_electron)  

# @ clerk/ 电子

[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_electron) [![Follow on X](https://img.shields.io/twitter/follow/clerk?style=social)](https://x.com/intent/follow?screen_name=clerk)

[更改日志](https://github.com/clerk/javascript/blob/main/packages/electron/CHANGELOG.md) • 妇女 [报告错误](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml) • 妇女 [请求特性](https://feedback.clerk.com/roadmap) • 妇女 [找人帮忙](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_electron)

## 开始

[办事员](https://clerk.com/?utm_source=github&utm_medium=clerk_electron) 是将认证和用户管理添加到您的 Electron 应用程序中的最简单方式.

> \[尖叫声\] `@clerk/electron` 以β为单位。 API在1.0前可能会有变化.

软件包有这些切入点:

-   `@clerk/electron` 运行在主进程.
-   `@clerk/electron/preload` 在预装入脚本中运行.
-   `@clerk/electron/react` 运行在渲染器过程中.
-   `@clerk/electron/storage` 是默认符号存储, 由 `electron-store`。 。 。 .
-   `@clerk/electron/passkeys` 为渲染器进程增加密码(WebAuthn)支持.

```ts
// main.ts
import { app, BrowserWindow, net, protocol } from 'electron';
import { createClerkBridge } from '@clerk/electron';
import { storage } from '@clerk/electron/storage';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';

const clerk = createClerkBridge({
  storage: storage(),
  renderer: {
    scheme: 'my-app',
    host: 'renderer',
  },
  passkeys: true,
});

if (clerk.isPrimaryInstance) {
  app.whenReady().then(() => {
    protocol.handle('my-app', request => {
      const url = new URL(request.url);
      const file = url.pathname === '/' ? 'index.html' : url.pathname;

      return net.fetch(pathToFileURL(join(__dirname, '../renderer', file)).toString());
    });

    const win = new BrowserWindow({
      webPreferences: {
        preload: join(__dirname, '../preload/index.js'),
      },
    });

    win.loadURL('my-app://renderer/');
  });
}
```

在Windows和Linux上,一个深层链接开始第二版的应用程序,所以回调只到达 通过Electron的单相锁运行过程. 当你配置一个渲染器方案时, `createClerkBridge` 默认获取此锁定, 并退出转发后的二次进程 他们的命令行参数。 打电话之前 `app.whenReady()`,当 `isPrimaryInstance` 实值 `false`。 。 。 . `app.quit()` 是一个同步的,所以 `whenReady` 仍然可以开火在一个 进程正在关闭. `cleanup()` 释放锁,除非应用程序已经拥有 马可斯不需要锁 深层链接通过 `open-url`所以书记官没有锁 `isPrimaryInstance` 总是 `true`。 。 。 .

如果应用程序管理锁, 在创建桥前先获取并禁用办事员的锁 管理层:

```ts
const gotTheLock = app.requestSingleInstanceLock();

if (!gotTheLock) {
  app.quit();
} else {
  createClerkBridge({
    storage: storage(),
    renderer: { scheme: 'my-app', host: 'renderer' },
    manageSingleInstanceLock: false,
  });
}
```

Linux 软件包还必须在其中注册渲染器方案 `.desktop` 条目,以便浏览器 启动应用程序 :

```ini
Exec=/path/to/my-app %U
MimeType=x-scheme-handler/my-app;
```

单位 `my-app://renderer/sign-in`, (中文(简体) ), `my-app` 这是计谋, `renderer` 是宿主, `my-app://renderer` 是来源,而且 `/sign-in` 是路径。 如果您的渲染器使用基于路径的路由,则服务来自同一来源的每条路由,并按需要返回渲染器入口.

```ts
// preload.ts
import { exposeClerkBridge } from '@clerk/electron/preload';

exposeClerkBridge({ passkeys: true });
```

```tsx
// renderer.tsx
import { ClerkProvider } from '@clerk/electron/react';
import { passkeys } from '@clerk/electron/passkeys';

<ClerkProvider
  publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}
  passkeys={passkeys}
>
  {/* ... */}
</ClerkProvider>;
```

设置特定应用产品符号,例如: `Acme Co/1.0.0`,通过 `userAgent` 改为 `createClerkBridge` 在创建渲染器窗口之前。 办事员保留Electron的平台细节,例如: `Macintosh` 或者说 `Windows`。用户Profile的会话活动然后显示您的产品代号为应用程序名:

```ts
createClerkBridge({
  storage: storage(),
  renderer: { scheme: 'my-app', host: 'renderer' },
  userAgent: 'Acme Co/1.0.0',
});
```

## 允许来源

将你的造型师的出处加进允许的出处 否则,书记官将拒绝同时载有两种材料的出纸器请求 `Origin` 还有一个 `Authorization` 标题有"既确定"奥里金",也禁止"认证"标题". 一旦有客户代号 渲染器就会发出两种信号.

```sh
curl -X PATCH https://api.clerk.com/v1/instance \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_origins": ["my-app://renderer", "http://localhost:5173"]}'
```

包含您的自定义方案来源, 并在开发过程中包含您的 dev 服务器来源 。 该命令取代了实例的全部列表, 因此包含实例已经允许的每个来源 。 要查看当前列表,请发送 `GET` 请求到同一终点.

## 内容安全政策

`@clerk/electron` 装入 Clerks 预建的 UI 在运行时从 Clerks 的 CDN 开始而不是捆绑它, 因此您的渲染器的内容安全政策必须允许 Clerk 的前端 API 主机 。 如果没有的话,UI脚本就无法加载,而Clark组件也永远不会渲染出.

替换 `{fapi_host}` 下面的你的例子 **前端 API** 主机,位于 [办事员板](https://dashboard.clerk.com/) 下级 **API 密钥**它包括: `clerk.` 部分(例如, `clerk.your-app.com` 生产中或 `your-slug.clerk.accounts.dev` (见E/CN.4/Sub.2/2000/L.31)。 不要使用账户门户 URL(`your-slug.accounts.dev`) (中文(简体) ). 主机阻止UI脚本装入.

```
default-src 'self';
script-src 'self' 'unsafe-inline' https://{fapi_host} https://challenges.cloudflare.com https://*.protect.clerk.com;
connect-src 'self' https://{fapi_host} https://*.protect.clerk.com:* https://clerk-telemetry.com;
img-src 'self' https://img.clerk.com data:;
style-src 'self' 'unsafe-inline';
worker-src 'self' blob:;
frame-src 'self' https://challenges.cloudflare.com https://*.protect.clerk.com;
form-action 'self';
```

> \[注\] 这个政策涵盖入住,入住,和热载UI. 书记员计费(Stripe)和其他功能需要更多的出处. 见文员 [CSP指南](https://clerk.com/docs/guides/secure/best-practices/csp-headers) 完整名单.

要么用一个 `<meta>` 在您的渲染器 HTML 中标记 :

```html
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' 'unsafe-inline' https://{fapi_host} https://challenges.cloudflare.com https://*.protect.clerk.com; connect-src 'self' https://{fapi_host} https://*.protect.clerk.com:* https://clerk-telemetry.com; img-src 'self' https://img.clerk.com data:; style-src 'self' 'unsafe-inline'; worker-src 'self' blob:; frame-src 'self' https://challenges.cloudflare.com https://*.protect.clerk.com; form-action 'self';"
/>
```

或,作为 [电子安全指南](https://www.electronjs.org/docs/latest/tutorial/security#7-define-a-content-security-policy) 建议:

```ts
// main.ts
import { app, session } from 'electron';

const fapiHost = 'clerk.your-app.com';

app.whenReady().then(() => {
  session.defaultSession.webRequest.onHeadersReceived((details, callback) => {
    callback({
      responseHeaders: {
        ...details.responseHeaders,
        'Content-Security-Policy': [
          [
            "default-src 'self'",
            `script-src 'self' 'unsafe-inline' https://${fapiHost} https://challenges.cloudflare.com https://*.protect.clerk.com`,
            `connect-src 'self' https://${fapiHost} https://*.protect.clerk.com:* https://clerk-telemetry.com`,
            "img-src 'self' https://img.clerk.com data:",
            "style-src 'self' 'unsafe-inline'",
            "worker-src 'self' blob:",
            "frame-src 'self' https://challenges.cloudflare.com https://*.protect.clerk.com",
            "form-action 'self'",
          ].join('; '),
        ],
      },
    });
  });
});
```

> \[注\] 当渲染器从维特等dev服务器上载时,HMR需要更宽松的规则. 添加 `'unsafe-eval'` 改为 `script-src` 和您的 dev 服务器的来源 `connect-src` (例如, `ws://localhost:<port> http://localhost:<port>`) (中文(简体) ). 许多应用软件在开发过程中跳过CSP,只应用于被包建的架构.

## 密码

密码以两种模式工作. 办事员为每个请求选择一个:

-   **渲染器模式**: 当窗口装入内容时 `https://` 从一个匹配您的 RP( 依赖方) ID 的源头, 渲染器使用 Chromium 的内置 WebAuthn 。 OS或浏览器同步证书. Windows Hello工作时没有设置. 在macOS上触摸ID需要用42号或以后的电能 [`app.configureWebAuthn`](https://www.electronjs.org/docs/latest/api/app#appconfigurewebauthnoptions-macos)。 。 。 .
-   **本地模式**: 当窗口装入本地捆绑时, 例如 `scheme://host`, WebAuthn 的出处检查拒绝了请求. 书记员将仪式通过IPC传送到主要流程. 可选 [`@clerk/electron-passkeys`](https://github.com/clerk/javascript/tree/main/packages/electron-passkeys) 本地模块然后调用 OS WebAuthn APIs (MacOS上的认证服务), `webauthn.dll` )),在视窗上.

Passkey自动填充依赖于WebAuthn有条件的调解,只有渲染器可以提供. 在本地模式下,登录形式通过"使用密码"动作提供密码. 它从不自己打开密码提示器.

### 设置

本地模式需要可选本地模块 :

```sh
pnpm add @clerk/electron-passkeys
```

```ts
// main process
import { createClerkBridge } from '@clerk/electron';
import { storage } from '@clerk/electron/storage';

createClerkBridge({ storage: storage(), passkeys: true });
```

```ts
// preload script
import { exposeClerkBridge } from '@clerk/electron/preload';

exposeClerkBridge({ passkeys: true });
```

```tsx
// renderer process (React)
import { ClerkProvider } from '@clerk/electron/react';
import { passkeys } from '@clerk/electron/passkeys';

<ClerkProvider
  publishableKey={publishableKey}
  passkeys={passkeys}
>
  {/* ... */}
</ClerkProvider>;
```

您的应用程序只在您通过密码时将密码捆绑并初始化 `passkeys` 道具 (英语). 如果你自己来管理书记员 而不是用 `ClerkProvider`把它接起来 `clerk.load()`数字 :

```ts
// renderer process (vanilla)
import { Clerk } from '@clerk/clerk-js';
import { createPasskeyProvider } from '@clerk/electron/passkeys';

const clerk = new Clerk(publishableKey);
createPasskeyProvider(clerk);
await clerk.load();
```

### 本地模式的 macOS 要求

就像iOS上的密码一样,macOS平台API需要验证您的应用程序和域名之间的关联:

1.  在书记板,去 [原生应用](https://dashboard.clerk.com/~/native-applications) 页面,并确保启用本地 API。 你的电动软件需要它.
2.  将 iOS 应用程序添加到 [原生应用](https://dashboard.clerk.com/~/native-applications) 在书记板上。 你需要你的应用程序的 App ID 前缀和 Bundle ID 。 一个Electron macOS应用程序使用与iOS应用程序相同的配置.
3.  签名您的应用程序 `com.apple.developer.associated-domains` 包含 `webcredentials:<rp-domain>`。这是 _限制_ 权利。 大楼必须嵌入一个提供配置,与相关域的能力相配合,用于捆绑的ID,而且应享权利还必须包括 `com.apple.application-identifier` 财务报告和审定财务报表 `com.apple.developer.team-identifier` 匹配配置图.

这些提示都针对相同的模糊"与域无关"错误:

-   用一个 **苹果开发** 身份证明(`mac.type: development` 电子制造器)和a **macOS 应用开发** 包括您的 Mac 的配置文件 。 同时在机器上安装配置文件( S)`~/Library/Developer/Xcode/UserData/Provisioning Profiles/<UUID>.provisionprofile`) (中文(简体) ).
-   复制 `.app` 捆绑在一起 `ditto`。其他复制方法可以打破应用程序封条,而macOS忽略了签名失败的应用程序的权益 `codesign --verify --deep --strict`。 。 。 .
-   `swcd` 在应用程序启动时注册域协会。 检查一下 `sudo swcutil show`如果卡住了,就赶紧跑 `sudo swcutil reset` 并重新启动.
-   优先使用默认(生产/CDN)关联路由. `?mode=developer` 与 `sudo swcutil developer-mode -e true` 也行,但常常是片状的.

Windows没有相应的要求. Linux没有本土模式,因此包括外置安全密钥在内的密码,只能在那里以渲染器模式工作.

## 支助

帮帮忙,来看我们 [支持页面](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_electron)。 。 。 .

## 捐款

我们欢迎所有社区的贡献! 如果你想以任何方式作出贡献,请阅读 [我们的捐款准则](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) 财务报告和审定财务报表 [行为守则](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md)。 。 。 .

## 警卫

`@clerk/electron` 遵循安全方面的良好做法,但不能保证100%的安全.

`@clerk/electron` 提供 **"就这样"** 没有 **保证**. 冒险使用.

_欲了解更多信息并报告安全问题,请参见我们 [安全记录](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)。 。 。 ._

## 许可证

本项目根据以下规定获得许可证: **麻省理工学院许可证**。 。 。 .

见 [自由主义](https://github.com/clerk/javascript/blob/main/packages/electron/LICENSE) 更多信息.

## 常见问题

### @clerk/electron 是什么？

电子的办事员 SDK

### 如何安装 @clerk/electron？

在项目目录运行 npm install @clerk/electron，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ~19\.0\.3 \|\| ~19\.1\.4 \|\| ~19\.2\.3 \|\| ~19\.3\.0-0）、electron（\>=28）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clerk/electron 支持 TypeScript 吗？

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

### @clerk/electron 支持 ESM 还是 CommonJS？

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

### @clerk/electron 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @clerk/electron 可以商用吗？

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

### @clerk/electron 的下载量有多少？

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

### @clerk/electron 还在维护吗？

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

