Communitygithub.com

deangilmoreremix/videoremix.vip2

Chrome 擴充功能驗證,整合 @clerk/chrome-extension,支援彈出視窗/側邊欄設定、透過 syncHost 進行 OAuth/SAML 驗證、為 Service Worker 與無頭擴充功能建立 Clerk 客戶端,以及穩定的 CRX ID。觸發時機:Chrome 擴充功能驗證、Plasmo Clerk、彈出視窗登入、syncHost、背景 Service Worker Token、createClerkClient、無頭擴充功能。

videoremix.vip2 是什麼?

此技能提供在 Chrome 擴充功能中整合 Clerk 驗證的完整指南與模式,涵蓋彈出視窗、側邊欄、Service Worker 和無頭擴充功能等不同架構。它詳細說明了 OAuth/SAML 無法在彈出視窗或側邊欄中運作的原因,並推薦使用 `syncHost` 將驗證委派給您的網頁應用程式,以支援這些方法。技能也解釋了為何電子郵件連結(魔法連結)在彈出視窗中無效,以及側邊欄在網頁應用程式登入後不會自動重新整理驗證狀態的限制。對於無 React 鈎子的背景腳本和內容腳本,它展示了如何使用 `createClerkClient()` 或訊息傳遞來獲取 Token。此外,它強調了在所有重構中都必須設定穩定的 CRX ID,否則每次重建都會破壞驗證,並提供了在 Clerk Dashboard 中設定允許來源的步驟。此技能支援 Plasmo 框架,並包含了常見陷阱的疑難排解表格,以及不同驗證方法所需的 Clerk 方案。

相容平台~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 將驗證委派給您的網頁應用程式
  2. 電子郵件連結(魔法連結)在彈出視窗中無法運作 -- 使用者點擊彈出視窗外部時,視窗會關閉,登入狀態會重置
  3. 側邊欄不會自動重新整理驗證狀態 -- 使用者必須在透過網頁應用程式登入後關閉並重新開啟側邊欄
  4. Service Worker 和內容腳本無法使用 Clerk React 鈎子 -- 請使用 createClerkClient() 或訊息傳遞
  5. 擴充功能網址使用 chrome-extension:// 而非 http:// -- 所有重新導向網址必須使用 chrome.runtime.getURL('.')
  6. 沒有穩定的 CRX ID,每次重建都會破壞驗證 -- 請在部署之前在 manifest 中設定 key
  7. 由於來源限制,內容腳本無法直接使用 Clerk -- Clerk 強制執行嚴格的允許來源
  8. 必須在 Clerk Dashboard 中停用機器人保護 -- 擴充功能環境不支援 Cloudflare 機器人偵測

驗證選項

方法彈出視窗側邊欄syncHost(搭配網頁應用程式)
電子郵件 + OTP是是是
電子郵件 + 連結否否是
電子郵件 + 密碼是是是
使用者名稱 + 密碼是是是
簡訊 + OTP是是是
OAuth(Google、GitHub 等)否否是
SAML否否是
通行金鑰是是是
Google One Tap否否是
Web3否否是

快速開始(Plasmo)

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

在 Clerk Dashboard 中啟用原生 API(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 -- 與網頁應用程式同步驗證

當您需要 OAuth、SAML,或希望擴充功能反映來自網頁應用程式的登入狀態時使用此模式。

運作方式:擴充功能透過 host_permissions 從您的網頁應用程式網域讀取 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 prop:

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 新增至網頁應用程式的允許來源:

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() 用於純 JavaScript / 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 標記即使在彈出視窗/側邊欄關閉時也能保持工作階段新鮮。沒有它,Token 會在 60 秒後過期。

使用純 JavaScript 的彈出視窗(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

無頭擴充功能(無彈出視窗、無側邊欄)

適用於完全在背景執行並與網頁應用程式同步的擴充功能。

使用 syncHost + 帶有 background: true 的 createClerkClient 來從網頁應用程式的 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 中為 syncHost 網域設定 host_permissions。

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

內容腳本

內容腳本會在注入網頁的隔離 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
  // 使用 token 進行已驗證的 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 > 允許來源。

Token 快取(在彈出視窗關閉後持續保留)

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 props 中缺少 CRX URL設定 afterSignOutUrl、signInFallbackRedirectUrl
OAuth 按鈕無效彈出視窗不支援 OAuth使用 syncHost 委派給網頁應用程式
網頁應用程式登入後驗證狀態過時未設定 syncHost新增 syncHost prop + host_permissions
網頁登入後側邊欄顯示已登出已知限制使用者必須關閉並重新開啟側邊欄
背景在 60 秒後無法取得 Token工作階段過期,無背景重新整理使用 createClerkClient({ background: true })
內容腳本無法存取 Clerk隔離環境 + 來源限制使用訊息傳遞給背景 Service Worker
重構後驗證中斷CRX ID 已輪替透過 .env.chrome 設定穩定金鑰
PLASMO_PUBLIC_ 變數未定義使用了錯誤的 env 檔案使用 .env.development,而不是 .env
機器人保護錯誤擴充功能不支援 Cloudflare在 Clerk Dashboard 中停用機器人保護
Token 快取未持續保留在彈出視窗中使用 localStorage使用 chrome.storage.local 或傳遞 tokenCache prop

方案需求

功能方案
基本彈出視窗驗證(電子郵件/密碼、OTP)免費
通行金鑰免費
syncHost需要 Pro(自訂網域)
透過 syncHost 的 OAuthPro + 在網頁應用程式上設定 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

相關技能