Getting started

快速入门指南

TL;DR（最快上手）

  1. bun install 2) cp .env.example .env.local 3) bun run init 4) bun run dev
bun install && cp .env.example .env.local && bun run init && bun run dev

10 分钟快速上手 NextJS Base

获取项目 · 环境配置 · 一键初始化 · 下一步

📋 概述

  • 环境：Node.js 20.9+，PostgreSQL 16+（或云服务），推荐包管器 bun。
  • 目标：10 分钟完成「安装 → 初始化 → 启动」。

本指南将帮助你在 10 分钟内完成项目的环境配置和启动。

前置要求

工具版本要求说明
Node.js20.9+推荐使用 LTS 版本
PostgreSQL16+或使用云数据库服务（如 Supabase、Neon）
bun/pnpm/npm/yarn最新版推荐使用 bun
Git最新版版本控制
GitHub 账号-用于 Fork 项目

🍴 获取项目

方式一：Fork 项目（推荐）

推荐使用 Fork：这样你可以保留自己的修改，同时方便接收上游更新。

  1. 访问 NextJS Base GitHub 仓库
  2. 点击右上角的 Fork 按钮
  3. 选择你的 GitHub 账号作为目标
  4. Fork 完成后，克隆你自己的仓库：
# 替换 your-username 为你的 GitHub 用户名
git clone https://github.com/your-username/nextjs-base.git my-project
cd my-project
  1. （可选）添加上游仓库以便同步更新：
git remote add upstream https://github.com/huglemon/nextjs-base.git

# 之后同步上游更新
git fetch upstream
git merge upstream/develop

方式二：使用模板创建

如果你想完全独立，不保留与原仓库的关联：

  1. 访问 NextJS Base GitHub 仓库
  2. 点击 Use this template → Create a new repository
  3. 填写你的仓库名称，点击创建
  4. 克隆新创建的仓库：
git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name

方式三：直接克隆（仅用于体验）

⚠️ 注意：直接克隆无法推送修改到原仓库，仅适合快速体验。

git clone https://github.com/huglemon/nextjs-base.git
cd nextjs-base

🔧 环境配置

1. 安装依赖（推荐使用 bun）

bun install

pnpm install

npm install

yarn install

2. 配置环境变量

复制环境变量模板：

cp .env.example .env.local

编辑 .env.local 文件：

# 数据库连接（必须）
DATABASE_URL="postgresql://username:password@localhost:5432/your_database?schema=public"

# Better Auth 配置（必须）
BETTER_AUTH_SECRET="your-secret-key-at-least-32-characters"
BETTER_AUTH_URL="http://localhost:3000"

# 云存储（可选，用于素材管理功能）
# 支持：r2, s3, aliyun, qiniu，通过 CDN_MODE 切换
CDN_MODE="r2"
R2_ACCOUNT_ID="your-account-id"
R2_ACCESS_KEY_ID="your-access-key"
R2_SECRET_ACCESS_KEY="your-secret-key"
R2_BUCKET_NAME="your-bucket"
R2_PUBLIC_URL="https://your-bucket.r2.cloudflarestorage.com"
# 更多存储服务配置请参考 /docs/admin/guides/STORAGE

3. 准备数据库

本地 PostgreSQL

# 登录 PostgreSQL
psql -U postgres

# 创建数据库
CREATE DATABASE your_database;

# 退出
\q

使用云数据库（推荐）

推荐使用以下云数据库服务，无需本地安装：

服务说明免费额度
Supabase开源 Firebase 替代品500MB
NeonServerless PostgreSQL512MB
Vercel PostgresVercel 原生集成256MB

创建数据库后，将连接字符串填入 .env.local 的 DATABASE_URL。

🚀 一键初始化

执行初始化

只需执行一个命令，完成所有初始化工作：

bun run init
pnpm run init
npm run init
yarn run init

这个命令会自动完成：

  1. ✅ 加载 .env.local 环境变量
  2. ✅ 生成 Prisma Client
  3. ✅ 创建数据库表结构
  4. ✅ 导入种子数据（RBAC 权限、菜单、示例数据）
  5. ✅ 创建超级管理员账户（交互式输入邮箱和密码）
╔═══════════════════════════════════════════════════════════╗
║           NextJS Base Admin - Initialization              ║
╚═══════════════════════════════════════════════════════════╝

[1/4] Checking environment...
   ✓ Loaded environment from .env.local
   ✓ DATABASE_URL found

[2/4] Setting up database schema...
   ✓ Prisma Client generated
   ✓ Database schema created

[3/4] Importing seed data...
   ✓ 43 permissions created
   ✓ 17 menus created
   ✓ 8 roles created
   ✓ 3 example records created

[4/4] Creating super admin account...
   Admin Email: [email protected]
   Admin Password: ********
   ✓ Super admin created

╔═══════════════════════════════════════════════════════════╗
║           ✅ Initialization Completed!                    ║
╚═══════════════════════════════════════════════════════════╝

非交互式初始化（CI/CD）

如果你想跳过交互式输入，可以通过环境变量预设管理员信息：

ADMIN_EMAIL=[email protected] ADMIN_PASSWORD=your-password ADMIN_NAME=Administrator bun run init
ADMIN_EMAIL=[email protected] ADMIN_PASSWORD=your-password ADMIN_NAME=Administrator pnpm run init
ADMIN_EMAIL=[email protected] ADMIN_PASSWORD=your-password ADMIN_NAME=Administrator npm run init
ADMIN_EMAIL=[email protected] ADMIN_PASSWORD=your-password ADMIN_NAME=Administrator yarn run init

分步执行

如果你想更细粒度地控制初始化过程：

bun run db:generate
bun run db:push
bun run db:seed
bun run db:admin
pnpm run db:generate
pnpm run db:push
pnpm run db:seed
pnpm run db:admin
npm run db:generate
npm run db:push
npm run db:seed
npm run db:admin
yarn run db:generate
yarn run db:push
yarn run db:seed
yarn run db:admin

🎉 启动项目

开发模式

bun run dev
pnpm run dev
npm run dev
yarn run dev

访问应用

页面地址
前台首页http://localhost:3000
后台管理http://localhost:3000/admin

使用你在初始化时创建的管理员账号登录后台。

⚠️ 安全提示：请使用强密码，并在生产环境中定期更换！

👤 超级管理员说明

什么是超级管理员？

超级管理员是系统中最高权限的用户：

属性值说明
roleadminBetter Auth 的 admin 角色
roles[]不需要 RBAC 角色
isBackendAllowedtrue允许访问后台

重要：role: 'admin' 拥有所有权限，不需要通过 RBAC 分配角色。

用户类型对比

类型rolerolesisBackendAllowed说明
普通用户user[]false只能访问前台
后台用户user['role_id']true需要分配 RBAC 角色
超级管理员admin[]true拥有所有权限

📦 种子数据说明

初始化脚本会导入以下预设数据（使用固定 ID，所有安装的系统数据一致）：

RBAC 数据

类型数量说明
权限 (Permissions)43包含 CRUD、RBAC、系统管理等权限
菜单 (Menus)17Dashboard、Example、RBAC、System、Links
角色 (Roles)8Admin Roles、User Roles 及其子角色

预设角色

角色名说明
Super Admin全量权限
Demo - Readonly全局只读
Admin - RBAC Ops (No Delete)RBAC 可写但无删除
Demo - RBAC Readonly + Example Write演示角色

示例数据

类型数量说明
Example Data3SmartCrudPage 演示数据

✅ 验证安装

检查清单

  • 项目成功启动，无报错
  • 可以访问前台首页
  • 可以访问后台登录页
  • 可以使用管理员账号登录
  • 后台菜单正常显示（Dashboard、Example、User & Permission、System、Links）
  • 可以访问 Example > Data Table > Basic 页面

常见问题

数据库连接失败

检查 .env.local 中的 DATABASE_URL 配置是否正确：

DATABASE_URL="postgresql://用户名:密码@主机:端口/数据库名?schema=public"

确保：

  • PostgreSQL 服务已启动
  • 用户名和密码正确
  • 数据库已创建
  • 端口号正确（默认 5432）
初始化脚本报错 "DATABASE_URL not found"

确保 .env.local 文件存在且格式正确：

# 检查文件是否存在
ls -la .env.local

# 检查内容
cat .env.local

注意：

  • 环境变量不要有多余的空格
  • 如果值包含特殊字符，用双引号包裹
Prisma 迁移失败

尝试重置数据库：

# 重置数据库（会删除所有数据）
bunx prisma migrate reset

# 重新执行初始化
bun run init
登录后台提示无权限

确保你的账户是超级管理员（role: 'admin'），或者被分配了正确的 RBAC 角色。

可以通过 Prisma Studio 检查用户数据：

bun run db:studio
pnpm run db:studio
npm run db:studio
yarn run db:studio
如何添加更多管理员？

方式一：通过命令行

bun run db:admin
pnpm run db:admin
npm run db:admin
yarn run db:admin

方式二：通过后台管理界面

登录后台 → User & Permission → Users → 创建用户 → 设置 role: admin

🎯 下一步

恭喜你完成了项目的初始化！接下来可以：

创建第一个页面

15 分钟完成公告管理 CRUD 页面

项目结构说明

5 分钟熟悉 app/(client) 与 admin 目录

整体架构

10 分钟了解数据流、权限与核心组件

完整示例

20 分钟阅读优惠券管理的端到端示例

📜 可用命令

命令说明
bun run init一键初始化（推荐）
bun run dev启动开发服务器
bun run build构建生产版本
bun run db:generate生成 Prisma Client
bun run db:push推送 Schema 到数据库
bun run db:migrate执行数据库迁移
bun run db:studio打开 Prisma Studio
bun run db:seed导入种子数据
bun run db:admin创建超级管理员

On this page

快速入门指南
📋 概述
前置要求
🍴 获取项目
方式一：Fork 项目（推荐）
方式二：使用模板创建
方式三：直接克隆（仅用于体验）
🔧 环境配置
1. 安装依赖（推荐使用 bun）
2. 配置环境变量
3. 准备数据库
🚀 一键初始化
执行初始化
非交互式初始化（CI/CD）
分步执行
🎉 启动项目
开发模式
访问应用
👤 超级管理员说明
什么是超级管理员？
用户类型对比
📦 种子数据说明
RBAC 数据
预设角色
示例数据
✅ 验证安装
检查清单
常见问题
🎯 下一步
📜 可用命令