Next.js 快速开始 | Nebutra Sailor Docs

前提条件

Node.js 22+

拥有 OPC 许可证的 Nebutra 账户（免费）

已有 Next.js 16 项目，或创建一个新项目：

npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

第一步：安装 SDK

npm install @nebutra/sdk

pnpm add @nebutra/sdk

第二步：配置环境变量

在项目根目录创建 .env.local 文件：

# 在 Nebutra 仪表板 → 设置 → API 密钥 中获取
NEBUTRA_API_KEY=nbk_live_xxxxxxxxxxxxxxxxxxxx
NEBUTRA_ORG_ID=org_xxxxxxxxxxxxxxxxxxxx

# 公开密钥——可以安全地暴露给浏览器
NEXT_PUBLIC_NEBUTRA_ORG_ID=org_xxxxxxxxxxxxxxxxxxxx

永远不要将 .env.local 提交到版本控制。请将其添加到 .gitignore。

第三步：初始化客户端

创建一个共享的 Nebutra 客户端：

import { createClient } from "@nebutra/sdk";

export const nebutra = createClient({
  apiKey: process.env.NEBUTRA_API_KEY!,
  orgId: process.env.NEBUTRA_ORG_ID!,
});

第四步：通过认证保护路由

使用 Nebutra 代理为 Server Component 添加认证（Next.js 16+ 使用 proxy.ts 替代 middleware.ts）：

import { withNebutraAuth } from "@nebutra/sdk/next";

export default withNebutraAuth({
  publicRoutes: ["/", "/sign-in", "/sign-up"],
});

export const config = {
  matcher: ["/((?!_next|favicon.ico).*)"],
};

第五步：在 Server Component 中读取当前用户

import { getAuth } from "@nebutra/sdk/next/server";

export default async function DashboardPage() {
  const { user, org } = await getAuth();

  if (!user) {
    redirect("/sign-in");
  }

  return (
    <div>
      <h1>欢迎，{user.firstName}</h1>
      <p>组织：{org.name}</p>
      <p>套餐：{org.plan}</p>
    </div>
  );
}

第六步：发起第一次 API 调用

import { NextResponse } from "next/server";
import { nebutra } from "@/lib/nebutra";
import { getAuth } from "@nebutra/sdk/next/server";

export async function GET() {
  const { org } = await getAuth();

  const projects = await nebutra.projects.list({
    orgId: org.id,
    limit: 20,
  });

  return NextResponse.json(projects);
}

第七步：在操作前检查权限

"use server";
import { requirePermission } from "@nebutra/sdk/next/server";
import { nebutra } from "@/lib/nebutra";

export async function deleteProject(projectId: string) {
  // 如果用户缺少 `project:delete` 范围，则抛出 403
  await requirePermission("project:delete");

  await nebutra.projects.delete(projectId);
}

准备就绪

核心概念

了解多租户和权限模型。

认证指南

深入了解认证流程和会话管理。

Webhooks

监听来自 Nebutra 租户的实时事件。

API 参考

完整的 REST API 文档。