Chrome 扩展认证模式
关键规则
- OAuth(Google、GitHub 等)和 SAML 不支持在弹窗或侧边栏中使用 — 应使用
syncHost将认证委托给您的 Web 应用 - 邮件链接(魔法链接)在弹窗中无效 — 用户点击弹窗外部时弹窗会关闭,导致登录状态重置
- 侧边栏不会自动刷新认证状态 — 用户通过 Web 应用登录后,必须关闭并重新打开侧边栏
- Service Worker 和 Content Script 无法使用 Clerk React hooks — 应使用
createClerkClient()或消息传递 - 扩展 URL 使用
chrome-extension://而非http://— 所有重定向 URL 必须使用chrome.runtime.getURL('.') - 没有稳定的 CRX ID,每次重建都会中断认证 — 在部署前,务必在 manifest 中配置
key - Content Script 不能直接使用 Clerk — 受限于源限制,Clerk 强制检查允许的来源
- 必须在 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(推荐):
- 访问 Plasmo Itero 生成密钥对
- 点击“生成密钥对” — 安全保存私钥,复制公钥和 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 的 OAuth | Pro + 在 Web 应用上配置 OAuth |
| 通过 syncHost 的 SAML | 企业版 |
| 机器人防护 | 不适用 — 扩展必须禁用 |
参见
clerk-setup— 初始 Clerk 安装clerk-custom-ui— 自定义流程与外观