解锁 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# oryarn create next-app
Next.js 项目建立之后安装 Clerk 包。
# npmnpm install @clerk/nextjs# yarnyarn add @clerk/nextjs# pnpmpnpm add @clerk/nextjs
1、填写 API keys 到本地项目
Clerk 安装完成后在项目根目录中新建
.env
文件,在里面填入 API keys
。API keys
可以在 Clerk 仪表盘中找到,路径为 Dashboard
-> Configure
-> Developers
下面第一个目录 API keys
。NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_CLERK_SECRET_KEY=sk_
2、创建中间件的替代方案
Clerk提供了多种中间件以便在不同框架中轻松集成身份验证和用户管理功能,最常用的中间件是保护路由中间件。由于目前 Pages 部署的项目暂不支持中间件的设定,建议在 Pages 中使用客户端验证的方法。
// pages/dashboard.jsximport { 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.tsximport '@/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 initgit add .git commit -m "First commit"git remote add origin "your Git address"git push -u origin master
通过以上步骤,您的项目代码将成功托管至 GitHub,为后续部署做好准备。
在部署设置页面填写
Environment Variables
。
这里可以仅填写连接的基本参数,部署后可以在项目中再次设定,在左侧导航栏中找到
Project Setting
,在页面中找到 Environment Variables
,修改或者新增后重新部署即可。
当出现 Congratulations 表示部署成功,部署大致会花费1-3分钟。如果项目出现部署失败,可以根据
Build Logs
和 Build Summary
信息修改项目,或者联系工作人员解决。
更多相关内容