@clerk/electron

中文文档
0.1.13发布于 2026/11/17MITTypeScriptESM + CJS构建来源已验证近 30 天下载 47.6万

电子的办事员 SDK

中文使用文档
文档目录10 节
  1. 开始
  2. 允许来源
  3. 内容安全政策
  4. 密码
  5. 设置
  6. 本地模式的 macOS 要求
  7. 支助
  8. 捐款
  9. 警卫
  10. 许可证


@ clerk/ 电子

Clerk documentation Follow on X

更改日志 • 妇女 报告错误 • 妇女 请求特性 • 妇女 找人帮忙

开始

办事员 是将认证和用户管理添加到您的 Electron 应用程序中的最简单方式.

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

软件包有这些切入点:

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

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

const gotTheLock = app.requestSingleInstanceLock();

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

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

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 是路径。 如果您的渲染器使用基于路径的路由,则服务来自同一来源的每条路由,并按需要返回渲染器入口.

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

exposeClerkBridge({ passkeys: true });
// 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的会话活动然后显示您的产品代号为应用程序名:

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

允许来源

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

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 主机,位于 办事员板 下级 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指南 完整名单.

要么用一个 <meta> 在您的渲染器 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';"
/>

或,作为 电子安全指南 建议:

// 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。 。 。 .
  • 本地模式: 当窗口装入本地捆绑时, 例如 scheme://host, WebAuthn 的出处检查拒绝了请求. 书记员将仪式通过IPC传送到主要流程. 可选 @clerk/electron-passkeys 本地模块然后调用 OS WebAuthn APIs (MacOS上的认证服务), webauthn.dll )),在视窗上.

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

设置

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

pnpm add @clerk/electron-passkeys
// main process
import { createClerkBridge } from '@clerk/electron';
import { storage } from '@clerk/electron/storage';

createClerkBridge({ storage: storage(), passkeys: true });
// preload script
import { exposeClerkBridge } from '@clerk/electron/preload';

exposeClerkBridge({ passkeys: true });
// 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()数字 :

// 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. 在书记板,去 原生应用 页面,并确保启用本地 API。 你的电动软件需要它.
  2. 将 iOS 应用程序添加到 原生应用 在书记板上。 你需要你的应用程序的 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没有本土模式,因此包括外置安全密钥在内的密码,只能在那里以渲染器模式工作.

支助

帮帮忙,来看我们 支持页面。 。 。 .

捐款

我们欢迎所有社区的贡献! 如果你想以任何方式作出贡献,请阅读 我们的捐款准则 财务报告和审定财务报表 行为守则。 。 。 .

警卫

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

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

欲了解更多信息并报告安全问题,请参见我们 安全记录。 。 。 .

许可证

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

见 自由主义 更多信息.

版本与发布记录

@clerk/electron 共发布 1,278 个版本,首次发布于 2026/06/15;过去 12 个月发布了 1278 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.13latest2026/11/17今天
0.1.14-canary.v20261117001008canary2026/11/17今天
0.1.13-canary.v202611162346222026/11/17今天
0.1.13-canary.v202611162315532026/11/17今天
0.1.13-canary.v202611162250302026/11/17今天
0.1.13-canary.v202611162203152026/11/17今天

其他发布通道:snapshot → 0.1.11-snapshot.v20261112232106,canary → 0.1.14-canary.v20261117001008。

关于 @clerk/electron 的常见问题

@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 和提交记录判断。