Communitygithub.com

deangilmoreremix/videoremix.vip2

Chrome 扩展认证与 @clerk/chrome-extension 集成 -- 弹窗/侧边栏设置、通过 syncHost 实现 OAuth/SAML 委托认证、以及面向 Service Worker 和无界面扩展的 createClerkClient 支持,且具备稳定的 CRX ID。

videoremix.vip2 是什么?

该技能(Skill)专注于在 Chrome 扩展中集成 Clerk 认证库,覆盖弹窗(Popup)、侧边栏(Side Panel)、后台 Service Worker、Content Script 以及无界面扩展等场景。它详细说明了不可直接在弹窗/侧边栏中使用 OAuth/SAML 的关键限制,并提供了通过 `syncHost` 将认证委托给 Web 应用的解决方案。同时,技能指导如何使用 `createClerkClient`(需从 `@clerk/chrome-extension/client` 导入)在 Vanilla JS 或 Service Worker 中管理会话与令牌,并强调在 Content Script 中必须通过消息传递获取认证状态。此外,技能还涵盖了如何通过配置稳定 CRX ID 来避免因扩展 ID 变更导致的认证中断,以及如何利用 `chrome.storage.local` 实现令牌跨弹窗持久化的最佳实践。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-chrome-extension-patterns

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Chrome 扩展认证模式

关键规则

  1. OAuth(Google、GitHub 等)和 SAML 不支持在弹窗或侧边栏中使用 — 应使用 syncHost 将认证委托给您的 Web 应用
  2. 邮件链接(魔法链接)在弹窗中无效 — 用户点击弹窗外部时弹窗会关闭,导致登录状态重置
  3. 侧边栏不会自动刷新认证状态 — 用户通过 Web 应用登录后,必须关闭并重新打开侧边栏
  4. Service Worker 和 Content Script 无法使用 Clerk React hooks — 应使用 createClerkClient() 或消息传递
  5. 扩展 URL 使用 chrome-extension:// 而非 http:// — 所有重定向 URL 必须使用 chrome.runtime.getURL('.')
  6. 没有稳定的 CRX ID,每次重建都会中断认证 — 在部署前,务必在 manifest 中配置 key
  7. Content Script 不能直接使用 Clerk — 受限于源限制,Clerk 强制检查允许的来源
  8. 必须在 Clerk Dashboard 中禁用机器人防护 — 扩展环境不支持 Cloudflare 机器人检测

认证方式

方法弹窗侧边栏syncHost(配合 Web 应用)
邮箱 + 一次性密码支持支持支持
邮箱 + 链接不支持不支持支持
邮箱 + 密码支持支持支持
用户名 + 密码支持支持支持
短信 + 一次性密码支持支持支持
OAuth(Google、GitHub 等)不支持不支持支持
SAML不支持不支持支持
Passkeys支持支持支持
Google One Tap不支持不支持支持
Web3不支持不支持支持

快速开始(Plasmo)

npx create-plasmo --with-tailwindcss --with-src my-extension
cd my-extension
npm install @clerk/chrome-extension

在 Clerk Dashboard 的“Native 应用”设置中启用 Native API。所有扩展集成都需要此项。

.env.development:

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-app.clerk.accounts.dev

src/popup.tsx:

import { ClerkProvider, Show, SignInButton, SignUpButton, UserButton } from '@clerk/chrome-extension'

const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const EXTENSION_URL = chrome.runtime.getURL('.')

if (!PUBLISHABLE_KEY) {
  throw new Error('缺少 PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY')
}

function IndexPopup() {
  return (
    <ClerkProvider
      publishableKey={PUBLISHABLE_KEY}
      afterSignOutUrl={`${EXTENSION_URL}/popup.html`}
      signInFallbackRedirectUrl={`${EXTENSION_URL}/popup.html`}
      signUpFallbackRedirectUrl={`${EXTENSION_URL}/popup.html`}
    >
      <Show when="signed-out">
        <SignInButton mode="modal" />
        <SignUpButton mode="modal" />
      </Show>
      <Show when="signed-in">
        <UserButton />
      </Show>
    </ClerkProvider>
  )
}

export default IndexPopup

为 SignInButton 使用 mode="modal" — 导航到单独的页面会破坏弹窗流程。

syncHost — 与 Web 应用同步认证

当您需要 OAuth、SAML 或希望扩展反映 Web 应用的登录状态时,使用此方法。

工作原理:扩展通过 host_permissions 读取您 Web 应用域名下的 Clerk 会话 Cookie。

步骤 1 — 环境变量:

.env.development:

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-app.clerk.accounts.dev
PLASMO_PUBLIC_CLERK_SYNC_HOST=http://localhost

.env.production:

PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_FRONTEND_API=https://clerk.your-domain.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://clerk.your-domain.com

步骤 2 — 添加 syncHost 属性:

const SYNC_HOST = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST

<ClerkProvider
  publishableKey={PUBLISHABLE_KEY}
  syncHost={SYNC_HOST}
  afterSignOutUrl="/"
  routerPush={(to) => navigate(to)}
  routerReplace={(to) => navigate(to, { replace: true })}
>

步骤 3 — 在 package.json 中配置 host_permissions:

{
  "manifest": {
    "key": "$CRX_PUBLIC_KEY",
    "permissions": ["cookies", "storage"],
    "host_permissions": [
      "$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
      "$CLERK_FRONTEND_API/*"
    ]
  }
}

步骤 4 — 通过 Clerk API 将扩展 ID 添加到 Web 应用的允许来源:

curl -X PATCH https://api.clerk.com/v1/instance \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-type: application/json" \
  -d '{"allowed_origins": ["chrome-extension://YOUR_EXTENSION_ID"]}'

在使用 syncHost 时,隐藏弹窗中不支持的认证方法:

<SignIn
  appearance={{
    elements: {
      socialButtonsRoot: 'plasmo-hidden',
      dividerRow: 'plasmo-hidden',
    },
  }}
/>

完整指南:references/sync-host.md

createClerkClient() 用于 Vanilla JS / Service Worker

从 @clerk/chrome-extension/client(而非 @clerk/chrome-extension)导入。

后台 Service Worker(src/background/index.ts):

import { createClerkClient } from '@clerk/chrome-extension/client'

const publishableKey = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY

async function getToken(): Promise<string | null> {
  const clerk = await createClerkClient({
    publishableKey,
    background: true,
  })
  if (!clerk.session) return null
  return await clerk.session.getToken()
}

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  getToken()
    .then((token) => sendResponse({ token }))
    .catch((error) => {
      console.error('[后台] 错误:', JSON.stringify(error))
      sendResponse({ token: null })
    })
  return true
})

background: true 标志即使在弹窗/侧边栏关闭时也能保持会话新鲜。没有它,令牌会在 60 秒后过期。

使用 Vanilla JS 的弹窗(src/popup.ts):

import { createClerkClient } from '@clerk/chrome-extension/client'

const EXTENSION_URL = chrome.runtime.getURL('.')
const POPUP_URL = `${EXTENSION_URL}popup.html`

const clerk = createClerkClient({ publishableKey })

clerk.load({
  afterSignOutUrl: POPUP_URL,
  signInForceRedirectUrl: POPUP_URL,
  signUpForceRedirectUrl: POPUP_URL,
  allowedRedirectProtocols: ['chrome-extension:'],
}).then(() => {
  clerk.addListener(render)
  render()
})

完整指南:references/create-clerk-client.md

无界面扩展(无弹窗、无侧边栏)

适用于完全在后台运行并与 Web 应用同步的扩展。

使用 syncHost + 带有 background: true 的 createClerkClient 来从 Web 应用的 Cookie 中读取认证状态。

import { createClerkClient } from '@clerk/chrome-extension/client'

const publishableKey = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const syncHost = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST

async function getAuthenticatedUser() {
  const clerk = await createClerkClient({
    publishableKey,
    syncHost,
    background: true,
  })
  return clerk.user
}

需要在 package.json 中为同步主机域名配置 host_permissions。

完整指南:references/headless-extension.md

Content Scripts

Content Script 在注入到网页的隔离 JavaScript 世界中运行。Clerk 不能直接使用 — 受限于源限制。

使用消息传递向后台 Service Worker 请求认证状态:

// content.ts
async function getToken(): Promise<string | null> {
  return new Promise((resolve) => {
    chrome.runtime.sendMessage({ type: 'GET_TOKEN' }, (response) => {
      resolve(response?.token ?? null)
    })
  })
}

async function main() {
  const token = await getToken()
  if (!token) return
  // 使用令牌进行经过认证的 API 调用
}

main()

完整指南:references/content-scripts.md

稳定的 CRX ID

如果没有固定的密钥,Chrome 会在构建时从一个随机密钥派生 CRX ID。每次重建时,该 ID 都会轮换,从而破坏允许的来源。

选项 A — Plasmo Itero(推荐):

  1. 访问 Plasmo Itero 生成密钥对
  2. 点击“生成密钥对” — 安全保存私钥,复制公钥和 CRX ID

选项 B — OpenSSL:

openssl genrsa -out key.pem 2048
# 使用 Plasmo Itero 转换或提取正确格式的公钥

.env.chrome:

CRX_PUBLIC_KEY="<来自 Itero 的公钥>"

package.json:

{
  "manifest": {
    "key": "$CRX_PUBLIC_KEY",
    "permissions": ["cookies", "storage"],
    "host_permissions": [
      "http://localhost/*",
      "$CLERK_FRONTEND_API/*"
    ]
  }
}

将 chrome-extension://YOUR_STABLE_CRX_ID 添加到 Clerk Dashboard > 允许来源。

令牌缓存(跨弹窗关闭持久化)

const tokenCache = {
  async getToken(key: string) {
    const result = await chrome.storage.local.get(key)
    return result[key] ?? null
  },
  async saveToken(key: string, token: string) {
    await chrome.storage.local.set({ [key]: token })
  },
  async clearToken(key: string) {
    await chrome.storage.local.remove(key)
  },
}

<ClerkProvider publishableKey={PUBLISHABLE_KEY} tokenCache={tokenCache}>
存储类型作用域清除时机
chrome.storage.local设备卸载或手动清除
chrome.storage.session会话浏览器关闭
chrome.storage.sync所有设备卸载(大小限制,8KB)
localStorage仅弹窗弹窗关闭 — 请勿用于认证

常见陷阱

症状原因修复
登录时重定向循环ClerkProvider 中缺少 CRX URL设置 afterSignOutUrl、signInFallbackRedirectUrl
OAuth 按钮不工作弹窗不支持 OAuth使用 syncHost 委托给 Web 应用
Web 应用登录后认证状态过期未配置 syncHost添加 syncHost 属性和 host_permissions
Web 登录后侧边栏显示未登录已知限制用户必须关闭并重新打开侧边栏
60 秒后后台无法获取令牌会话过期,无后台刷新使用 createClerkClient({ background: true })
Content Script 无法访问 Clerk隔离环境 + 源限制使用消息传递到后台 Service Worker
重构后认证中断CRX ID 轮换通过 .env.chrome 配置稳定密钥
PLASMO_PUBLIC_ 变量未定义环境文件错误使用 .env.development,而非 .env
机器人防护错误扩展不支持 Cloudflare在 Clerk Dashboard 中禁用机器人防护
令牌缓存未持久化在弹窗中使用 localStorage使用 chrome.storage.local 或传递 tokenCache 属性

计划要求

功能计划
基本弹窗认证(邮箱/密码、OTP)免费
Passkeys免费
syncHost需要 Pro(自定义域名)
通过 syncHost 的 OAuthPro + 在 Web 应用上配置 OAuth
通过 syncHost 的 SAML企业版
机器人防护不适用 — 扩展必须禁用

参见

  • clerk-setup — 初始 Clerk 安装
  • clerk-custom-ui — 自定义流程与外观

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

相关技能