边缘开发者平台
  • Pages
    • 产品简介
    • 快速开始
      • 导入 Git 仓库
      • 从模板开始
      • 直接上传
    • 框架指南
    • 项目指南
      • 项目管理
      • edgeone.json
      • 错误码
    • 构建指南
    • 部署指南
      • 概览
      • 触发部署
      • 管理部署
      • 部署按钮
    • 域名管理
      • 概览
      • 自定义域名
      • 配置 HTTPS 证书
      • 如何配置 DNS 的 CNAME 记录
    • Pages Functions
    • KV 存储
    • 边缘 AI
    • API Token
    • EdgeOne CLI
    • Pages MCP
    • 集成指南
      • 数据库
        • Supabase 集成
        • Pages KV 集成
      • 电商
        • WooCommerce 集成
      • 支付
        • Stripe 集成
      • CMS
        • WordPress 集成
        • Contentful 集成
        • Sanity 集成
      • 身份验证
        • Clerk 集成
    • 最佳实践
      • 使用 Deepseek-R1 模型快速搭建对话型AI站点
      • 使用 WordPress + WooCommerce 和 GatsbyJS 搭建电商平台
      • 使用 Supabase 和 Stripe 搭建 SaaS 站点
      • 如何快速搭建公司品牌站点
    • 迁移指南
      • 从 Vercel 迁移至 EdgeOne Pages
      • 从 Cloudflare Pages 迁移至 EdgeOne Pages
      • 从 Netlify 迁移至 EdgeOne Pages
    • 排障指南
    • 常见问题
    • 联系我们
    • 产品动态
解锁 1年EdgeOne + 1TB CDN: 加入我们的开发者之旅
立即开始!
当前为国际站中文文档,如需访问中国站文档,请点击这里

Clerk 集成

Clerk 是一套完整的可嵌入 UI、灵活的 API 和管理仪表板,用于验证和管理您的用户。


概览

本指南为开发者提供快速集成 Clerk 的步骤说明,并提供将项目部署在 EdgeOne Pages 的教程。下文将详细介绍如何在项目中集成 Clerk,快速完成项目中的用户管理功能开发。


快速入门

您可以选择 Pages 提供的 Clerk 集成模版,快捷迅速进入到开发当中,点击 Clerk Authentication Starter 模版。本教程大致分为三步:Clerk 配置、本地集成、EdgeOne Pages 部署配置,下面将详细介绍每个步骤的具体操作。


Clerk 配置

前往 clerk.com 注册账户并新建项目,第一次登录需要Create your project,之后会进入到 Overview,在 Overview 页面找到对应的开发框架,本指南以 Next.js 项目,路由模式为 Pages Router 为例。

如果还没有建立 Next.js 项目,可以通过以下命令行建立 Next.js 项目。
npx create-next-app@latest
# or
yarn create next-app
Next.js 项目建立之后安装 Clerk 包。
# npm
npm install @clerk/nextjs
# yarn
yarn add @clerk/nextjs
# pnpm
pnpm add @clerk/nextjs


1、填写 API keys 到本地项目

Clerk 安装完成后在项目根目录中新建 .env 文件,在里面填入 API keysAPI keys 可以在 Clerk 仪表盘中找到,路径为 Dashboard -> Configure -> Developers 下面第一个目录 API keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_
CLERK_SECRET_KEY=sk_


2、创建中间件的替代方案

Clerk提供了多种中间件以便在不同框架中轻松集成身份验证和用户管理功能,最常用的中间件是保护路由中间件。由于目前 Pages 部署的项目暂不支持中间件的设定,建议在 Pages 中使用客户端验证的方法。
// pages/dashboard.jsx
import { useAuth } from "@clerk/nextjs";
import { useRouter } from "next/router";
import { useEffect } from "react";

export default function Dashboard() {
const { isLoaded, userId, isSignedIn } = useAuth();
const router = useRouter();

useEffect(() => {
// 等待Auth状态加载完成
if (isLoaded && !isSignedIn) {
router.replace(/sign-in?redirect_url=${encodeURIComponent(router.asPath)});
}
}, [isLoaded, isSignedIn, router]);

// 显示加载状态或未授权状态
if (!isLoaded || !isSignedIn) {
return <div>Loading...</div>;
}

// 用户已验证,显示内容
return (
<div></div>
);
}
或者创建统一的受保护页面包装器来进行管理。


3、添加 Clerk 组件到代码中

添加 <ClerkProvider> 组件到你的应用,这个组件功能是提供会话和用户上下文,建议在应用入口接入。

此外,还可以将 <SignedIn> <SignedOut> <UserButton> <SignInButton> 组件添加到你的应用,这些组件的作用是:
<SignedIn>:只有登录后才能看到此组件的子项。
<SignedOut>: 只有退出后才能看到此组件的子项。
<UserButton>:显示用户头像,包含用户操作的下拉菜单。
<SignInButton>:链接到登录页面的无样式组件。
// pages/_app.tsx

import '@/styles/globals.css'
import { ClerkProvider, SignInButton, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
import type { AppProps } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
return (
<ClerkProvider {...pageProps}>
<SignedOut>
<SignInButton />
</SignedOut>
<SignedIn>
<UserButton />
</SignedIn>
<Component {...pageProps} />
</ClerkProvider>
)
}

export default MyApp



部署到 EdgeOne Pages

这一节将会详细介绍如何在 EdgeOne Pages 部署中接入 Clerk,下面分为直接从 Pages template 中选择 Clerk 模版部署,以及部署自定义项目到 Pages 中。在这一步中如果没有关联线上 Git 的需要完成 Git 授权(支持 Github/Gitee)。


1、部署 Pages template Clerk 模版(模版部署)

您可以直接使用 EdgeOne Pages 的 Clerk 前端模版,点击 Create project -> Start from template,选择 Authentication->Clerk-> Clerk Authentication Starter



然后点击 Deploy,填写 Environment Variables,参数说明如下:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:Clerk 公钥。
NEXT_PUBLIC_CLERK_SIGN_IN_URL:登录页面地址。
NEXT_PUBLIC_CLERK_SIGN_UP_URL:注册页面地址。
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL:登录后重定向的地址。
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL:注册后重定向地址。

点击 Create 开始部署。


2、部署自定义项目到 Pages 中(自定义部署)

1. 创建新仓库
登录您的 GitHub 账户,进入 Dashboard
点击右上角的 New 按钮
填写仓库名称、描述等信息
选择仓库可见性(Public 或 Private)
点击 Create repository 完成创建

2. 上传本地项目
在本地项目目录下初始化 Git(如未初始化)
将项目文件提交并推送到新建的远程仓库

然后在本地关联远程仓库,并上传本地代码。
# Push your code to your git repository (e.g. GitHub, Gitee).

git init
git add .
git commit -m "First commit"
git remote add origin "your Git address"
git push -u origin master
通过以上步骤,您的项目代码将成功托管至 GitHub,为后续部署做好准备。

进入到 EdgeOne Pages 控制台中,上传自己的项目到 Github,点击 Create project -> Import Git repository,选择您的项目。

在部署设置页面填写 Environment Variables

这里可以仅填写连接的基本参数,部署后可以在项目中再次设定,在左侧导航栏中找到 Project Setting,在页面中找到 Environment Variables,修改或者新增后重新部署即可。

当出现 Congratulations 表示部署成功,部署大致会花费1-3分钟。如果项目出现部署失败,可以根据 Build LogsBuild Summary 信息修改项目,或者联系工作人员解决。



更多相关内容

了解 Clerk 更多的操作: Clerk 使用文档