文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>Pages>集成指南>身份验证>Clerk 集成

Clerk 集成

最近更新时间：2026-01-09 17:47:33

我的收藏

本页目录：

本指南为开发者提供快速集成 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 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.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 前端模板，点击 创建项目 -> 从模板开始 ，选择 Authentication->Clerk-> Clerk Authentication Starter。

然后点击 Deploy，填写 环境变量，参数说明如下：
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：注册后重定向地址。
点击 立即部署 开始部署。

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，点击 创建项目 -> 导入 Git 仓库，选择您的项目。
在部署设置页面填写 环境变量。

这里可以仅填写连接的基本参数，部署后可以在项目中再次设定，在左侧导航栏中找到 项目设置，在页面中找到 环境变量，修改或者新增后重新部署即可。
当出现 “恭喜！” 表示部署成功，部署大致会花费1-3分钟。如果项目出现部署失败，可以根据 构建日志 和 构建产物 信息修改项目，或者联系工作人员解决。


更多相关内容

了解 Clerk 更多的操作，请参见 Clerk 使用文档。


中国站
目录