Chrome 擴充功能模式
關鍵規則
- OAuth(Google、GitHub 等)和 SAML 不支援在彈出視窗或側邊欄中使用 -- 請使用
syncHost將驗證委派給您的網頁應用程式 - 電子郵件連結(魔法連結)在彈出視窗中無法運作 -- 使用者點擊彈出視窗外部時,視窗會關閉,登入狀態會重置
- 側邊欄不會自動重新整理驗證狀態 -- 使用者必須在透過網頁應用程式登入後關閉並重新開啟側邊欄
- Service Worker 和內容腳本無法使用 Clerk React 鈎子 -- 請使用
createClerkClient()或訊息傳遞 - 擴充功能網址使用
chrome-extension://而非http://-- 所有重新導向網址必須使用chrome.runtime.getURL('.') - 沒有穩定的 CRX ID,每次重建都會破壞驗證 -- 請在部署之前在 manifest 中設定
key - 由於來源限制,內容腳本無法直接使用 Clerk -- Clerk 強制執行嚴格的允許來源
- 必須在 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(建議):
- 前往 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 > 允許來源。
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 的 OAuth | Pro + 在網頁應用程式上設定 OAuth |
| 透過 syncHost 的 SAML | 企業版 |
| 機器人保護 | 不適用 -- 必須為擴充功能停用 |
另請參閱
clerk-setup- 初始 Clerk 安裝clerk-custom-ui- 自訂流程與外觀