Communitygithub.com

deangilmoreremix/videoremix.vip2

Clerk Billing 订阅管理 - 渲染 Clerk 的 PricingTable 和应用内结账抽屉,配置订阅计划、B2B 席位限制计划、使用 has() 的功能授权以及计费 Webhook。适用于 SaaS 货币化、计划控制、结账流程、试用、发票和订阅生命周期管理。

videoremix.vip2 是什么?

该技能专注于 Clerk Billing 的配置与集成,用于管理 SaaS 应用的订阅和计费。它提供了 `enable billing` CLI 命令和 PLAPI 接口,以实现程序化计费配置,以及从 Dashboard 进行 UI 配置。核心功能包括使用 `<PricingTable />` 和 `<CheckoutButton />` 渲染定价页面,并通过 `auth().has({ feature })` 或 `auth().has({ plan })` 实现功能授权和计划级别的访问控制。它同时支持 B2C(个人用户订阅)和 B2B(组织订阅与席位限制计划)模式。此外,还详细包含了用于处理订阅生命周期事件(如创建、更新、续订和取消)的计费 Webhook 事件目录。该技能适用于 Next.js 等使用 Clerk.js 和 `@clerk/nextjs` 的平台。

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

在你喜欢的 AI 中提问

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

文档

计费

注意,先决条件。 在使用任何 <PricingTable />、<CheckoutButton />、has({ plan }) 或 has({ feature }) 之前,必须先启用计费。有两种方式:(1) Dashboard → Billing → Settings,或 (2) clerk enable billing(参见下文“Agent-first: 程序化计费配置”)。启用后会自动创建默认的 free_user / free_org 计划。开发实例可以使用共享的 Clerk 开发网关(无需 Stripe 账户);生产环境则需要 Stripe 账户来处理付款。

注意:计费 API 仍处于实验阶段。请锁定你的 @clerk/nextjs 和 clerk-js 包版本。支持的版本表请参见 clerk 技能。

快速开始

  1. 启用计费,通过 Dashboard → Billing → Settings 或 clerk enable billing(参见 Agent-first 部分)。跳过此步骤会在开发环境中抛出 cannot_render_billing_disabled 错误,在生产环境则渲染为空。

  2. 在对应的标签页中创建计划,Dashboard → Billing → Plans。两个标签页,slug 在每个标签页内作用域限定,创建后不可移动:

    • 用户计划(User Plans) → <PricingTable />(默认为 for="user")
    • 组织计划(Organization Plans) → <PricingTable for="organization" />

    标签页错误是 <PricingTable /> 渲染为空的头号原因。计划存在于 Clerk 中;不会同步到 Stripe。

  3. 在计划内添加功能,在 Dashboard → Billing → Plans 中打开该计划,使用其功能(Features)部分。功能在每个计划内作用域限定,不是全局的。同一个 slug 可以附加到多个计划;如果用户的活跃计划包含该 slug,则 has({ feature: 'export' }) 将匹配。

  4. 渲染 <PricingTable />(对于 B2B,传入 for="organization")。

  5. 使用 auth() 中的 has({ plan }) 或 has({ feature }) 控制访问。

  6. 处理订阅生命周期的计费 Webhook。

Dashboard 快捷方式

操作URL
启用计费https://dashboard.clerk.com/last-active?path=billing/settings
创建/编辑计划https://dashboard.clerk.com/last-active?path=billing/plans
成员模式 (B2C + B2B 共存)https://dashboard.clerk.com/last-active?path=organizations-settings
编辑功能计划 → 点击一个计划 → 功能(Features)部分 (无直接 URL)

Agent-first: 程序化计费配置

完整的计费配置(启用开关、计划、功能、计划-功能附件)都可以通过 PLAPI 编辑,而无需接触 Dashboard。这对于 Agent 播种计划、跨实例复制配置或对计费结构进行版本控制非常有用。

前置条件:项目已链接到 Clerk 应用(clerk auth login + clerk link,参见 clerk-setup)。

通过 CLI 启用计费

clerk enable billing                # 两者都启用 (默认,自动创建 free_user + free_org 计划)
clerk enable billing --for org      # 仅组织
clerk enable billing --for user     # 仅用户

拉取当前计费配置

clerk config pull --keys billing > billing.json

这将把当前链接实例的计费配置(开关 + 计划 + 功能)写入到 billing.json 文件中。

编辑和应用

编辑 billing.json 以添加/删除计划或功能,然后预览差异并应用:

clerk config patch --file billing.json --dry-run
clerk config patch --file billing.json

传入 --instance prod 以定位生产实例而非开发实例。

原始 PATCH (完全控制)

用于一次性更新计划/功能,无需配置文件:

clerk api --platform PATCH /v1/platform/applications/<app_id>/instances/<ins_id>/config \
  -d '{"billing":{"plans":[{"slug":"pro","name":"Pro","amount":2000,"currency":"usd","payer_type":"user","is_recurring":true}],"features":[{"slug":"export","name":"Export"}]}}'

说明

  • 这处理的是计费配置(开关 + 计划 + 功能目录)。订阅生命周期(用户选择计划、结账、续订、取消)仍然通过 <PricingTable /> + 计费 Webhook 流转,生命周期事件请参见 clerk-webhooks 技能。
  • 顶级 features 映射操作和计划-功能附件(同步)完全通过 PLAPI 计费配置处理器支持。

你需要什么?

任务参考
<PricingTable /> 属性、<CheckoutButton />、<Show> 计费模式references/billing-components.md
B2C 模式 (个人用户订阅、Membership optional 前置条件)references/b2c-patterns.md
B2B 模式 (组织订阅、席位限制计划、管理员控制的计费 UI)references/b2b-patterns.md
Webhook 事件目录、负载结构、处理器模板references/billing-webhooks.md

参考

参考描述
references/billing-components.md<PricingTable /> 和订阅 UI
references/b2c-patterns.mdB2C 订阅计费模式
references/b2b-patterns.md使用组织订阅和席位限制计划进行 B2B 计费
references/billing-webhooks.md订阅生命周期事件处理

文档

功能 vs 计划:何时使用哪种

在控制特定能力时使用 has({ feature: 'slug' }),例如:导出、分析、API 访问、审计日志。

在控制层级时使用 has({ plan: 'slug' }),例如:显示专业版仪表盘、检查组织订阅级别、重定向免费用户。

场景正确的检查方式
控制“导出 CSV”按钮has({ feature: 'export' })
控制“分析”部分has({ feature: 'analytics' })
控制整个 /dashboard/prohas({ plan: 'pro' })
检查组织是否拥有团队订阅has({ plan: 'org:team' })
控制 SSO 配置has({ feature: 'sso' })

当用户说“控制导出功能”或“控制分析”时,始终使用 has({ feature })。仅当控制的是计划层级本身,而非其中的特定能力时,才使用 has({ plan })。

关键模式

1. 渲染定价表

使用单个组件向用户展示可用计划:

import { PricingTable } from '@clerk/nextjs'

export default function PricingPage() {
	return (
		<main>
			<h1>选择一个计划</h1>
			<PricingTable />
		</main>
	)
}

<PricingTable /> 自动渲染在 Clerk Dashboard 中配置的所有计划。选择计划会打开 Clerk 的应用内结账抽屉。基本用法无需属性。对于 B2B,传入 for="organization" 以渲染组织级别的计划,而非用户计划。

2. 检查功能授权 (服务端)

按单个功能进行控制,这是针对特定能力的首选方法:

import { auth } from '@clerk/nextjs/server'

export default async function AnalyticsPage() {
	const { has } = await auth()

	const canViewAnalytics = has({ feature: 'analytics' })
	const canExport = has({ feature: 'export' })

	return (
		<div>
			{canViewAnalytics && <AnalyticsChart />}
			{canExport && <ExportButton />}
		</div>
	)
}

功能在 Clerk Dashboard → Billing → Features 中配置,并分配给计划。在控制细粒度能力时,使用 has({ feature }) 而非 has({ plan }),检查功能,而非计划。

3. 检查功能授权 (客户端)

对于客户端功能控制,使用 useAuth()。结合服务端检查以获得全面覆盖:

'use client'
import { useAuth } from '@clerk/nextjs'

export function FeatureGatedUI() {
	const { has, isLoaded } = useAuth()
	if (!isLoaded) return null

	const canExport = has?.({ feature: 'export' })
	const canAnalytics = has?.({ feature: 'analytics' })

	return (
		<div>
			{canAnalytics && <AnalyticsSection />}
			{canExport ? <ExportButton /> : <UpgradeToExport />}
		</div>
	)
}

服务端组件使用 auth(),客户端组件使用 useAuth()。两者都支持 has({ feature }) 和 has({ plan })。

4. 服务端检查订阅计划

按订阅计划控制访问(用于层级级别的控制,而非单个功能):

import { auth } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'

export default async function ProDashboard() {
	const { has } = await auth()

	if (!has({ plan: 'pro' })) {
		redirect('/pricing')
	}

	return <ProFeatures />
}

5. 客户端计划检查

对于客户端组件,使用 useAuth() 钩子:

'use client'
import { useAuth } from '@clerk/nextjs'

export function UpgradePrompt() {
	const { has } = useAuth()

	if (has?.({ plan: 'pro' })) {
		return null
	}

	return (
		<div>
			<p>升级到专业版以使用此功能</p>
			<a href="/pricing">查看计划</a>
		</div>
	)
}

6. B2B 基于席位的组织计费

组织计划可以带有一个席位限制(成员上限),Clerk 在邀请时会强制执行。在对组织方计划检查时使用 org: slug 前缀(例如 has({ plan: 'org:team' }))以保持控制明确无误。使用 <PricingTable for="organization" /> 渲染 B2B 定价页面,并使用 <OrganizationProfile /> 作为组织账户的计费 UI。

有关层级计划命名、席位限制不变性、仅管理员计费和 Webhook 处理器,请参见 references/b2b-patterns.md。

7. 显示订阅状态

使用 has({ plan }) 检查特定计划,或使用客户端组件中的 useSubscription() 获取完整订阅详情。不要直接从 sessionClaims 读取计划信息,这不是受支持的路径。

服务端组件,检查特定计划:

import { auth } from '@clerk/nextjs/server'

export default async function AccountPage() {
	const { has } = await auth()

	const currentPlan = has({ plan: 'pro' })
		? 'pro'
		: has({ plan: 'starter' })
			? 'starter'
			: 'free'

	return (
		<div>
			<h2>当前计划</h2>
			<p>你当前使用的是 {currentPlan} 计划</p>
			{currentPlan === 'free' && <a href="/pricing">升级</a>}
		</div>
	)
}

客户端组件,通过 useSubscription() 获取完整订阅详情:

'use client'
import { useSubscription } from '@clerk/nextjs/experimental'

export function SubscriptionDetails() {
	const { data: subscription, isLoading } = useSubscription()
	if (isLoading) return null
	if (!subscription) return <a href="/pricing">选择一个计划</a>

	return (
		<div>
			<p>状态: {subscription.status}</p>
			{subscription.nextPayment && (
				<p>下次付款: {subscription.nextPayment.date.toLocaleDateString()}</p>
			)}
		</div>
	)
}

useSubscription() 仅用于显示。对于授权检查(控制内容或路由),始终使用 has({ plan }) 或 has({ feature })。

8. 按计划保护 API 路由

使用 auth() 控制 API 路由:

import { auth } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'

export async function GET() {
	const { has } = await auth()

	if (!has({ plan: 'pro' })) {
		return NextResponse.json({ error: '需要专业版计划' }, { status: 403 })
	}

	return NextResponse.json({ data: '高级数据' })
}

9. 处理计费 Webhook

Clerk 事件名称与 Stripe 事件名称不同。 Clerk 计费 Webhook 使用点号表示法和驼峰命名,而非 Stripe 的下划线格式。

没有 subscription.canceled 事件。取消操作在项目级别触发,事件为 subscriptionItem.canceled。

意图Stripe 事件名称Clerk 事件名称
订阅已创建customer.subscription.createdsubscription.created
订阅已更新customer.subscription.updatedsubscription.updated
订阅活跃(无)subscription.active
订阅逾期(无)subscription.pastDue
订阅项目已取消customer.subscription.deletedsubscriptionItem.canceled
订阅项目逾期invoice.payment_failedsubscriptionItem.pastDue
订阅项目已更新(无)subscriptionItem.updated
订阅项目活跃(无)subscriptionItem.active
订阅项目即将续订(无)subscriptionItem.upcoming
订阅项目已结束(无)subscriptionItem.ended
订阅项目已放弃(无)subscriptionItem.abandoned
订阅项目已过期(无)subscriptionItem.expired
订阅项目不完整(无)subscriptionItem.incomplete
免费试用即将结束(无)subscriptionItem.freeTrialEnding
付款尝试已创建(无)paymentAttempt.created
付款尝试已更新(无)paymentAttempt.updated

在 evt.type 检查中,始终使用 Clerk 的事件名称,绝不使用 Stripe 的。

负载结构。 Clerk 计费 Webhook 负载是嵌套的。订阅实体位于 evt.data.payer 下(字段:user_id?、organization_id?)。计划信息位于每个项目中的 evt.data.items[i].plan.slug 下。订阅 ID 即为 evt.data.id。订阅项目没有返回 subscription_id 字段的反向引用,因此在 subscriptionItem.* 处理器中,你需要通过项目 ID(evt.data.id)或通过付款方加计划来查找记录。

用于锚定模式的最小处理器(从 @clerk/nextjs/webhooks 导入,验证,根据 Clerk 事件名称分支):

import { verifyWebhook } from '@clerk/nextjs/webhooks'
import { NextRequest } from 'next/server'
import { db } from '@/lib/db'

export async function POST(req: NextRequest) {
	let evt
	try {
		evt = await verifyWebhook(req)
	} catch {
		return new Response('验证失败', { status: 400 })
	}

	if (evt.type === 'subscription.created') {
		const { id, payer, items, status } = evt.data
		const entityId = payer.user_id ?? payer.organization_id
		// ... 处理新订阅 ...
	}

	if (evt.type === 'subscriptionItem.canceled') {
		const { id, payer, items } = evt.data
		const planSlug = items?.[0]?.plan?.slug
		// ... 处理订阅取消 ...
	}

	return new Response('Webhook 已接收', { status: 200 })
}

10. 试用期

在 Clerk Dashboard → Billing → Plans 中编辑计划时,可以为任何计费计划添加试用期。

试用期在计划级别配置:

{
  "slug": "pro",
  "name": "Pro",
  "amount": 2000,
  "currency": "usd",
  "trial_period_days": 14
}

试用期会在每个计费周期首次续订时自动应用。试用期结束时,会触发 subscriptionItem.freeTrialEnding webhook。

11. 发票

发票通过 Stripe 自动生成。Clerk 不直接创建或管理发票。如需自定义发票,请在 Stripe Dashboard 中配置。

计费 Webhook paymentAttempt.* 包含有关付款尝试的信息。

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

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

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

相关技能