shadcn-nextjs-boilerplate布局体系源码解析：Sidebar、Navbar与三层架构的设计思路

shadcn-nextjs-boilerplate布局体系源码解析：Sidebar、Navbar与三层架构的设计思路

【免费下载链接】shadcn-nextjs-boilerplateShadcn UI NextJS Boilerplate ⚡️ Free Open-source ChatGPT UI Admin Dashboard Template - Horizon AI Boilerplate项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-nextjs-boilerplate

shadcn-nextjs-boilerplate是一款免费的开源 Next.js 后台仪表盘模板（Horizon AI Boilerplate），内置 ChatGPT 风格的 AI 对话界面、Supabase 认证与 Stripe 支付。本文带你读懂它的布局体系源码：Sidebar 侧边栏、Navbar 导航栏如何与"三层架构"协作，帮你在 30 分钟内搭出自己的管理后台。

🧭 先看整体：三层布局架构

这个项目的页面不是一块大 HTML，而是由三层布局像"套娃"一样叠起来的：

层级	文件	职责
第一层：根布局	app/layout.tsx	挂载主题切换（ThemeProvider）与 Supabase 认证上下文（SupabaseProvider）
第二层：仪表盘布局	components/layout/index.tsx	组合 Sidebar + Navbar + 主内容区 + Footer，并注入用户状态
第三层：页面内容	app/dashboard/main/page.tsx等	各功能页只关心业务 UI，复用components/layout/innerContent.tsx的居中容器

RootLayout（主题 + 认证） └─ DashboardLayout（Sidebar + Navbar + main + Footer） └─ InnerContent（内容居中容器，最大宽度 1170px） └─ 具体页面

第二层是整个布局体系的心脏，源码在components/layout/index.tsx（第 29~31 行）：

• UserContext / UserDetailsContext：把登录用户对象、用户资料注入全局，Sidebar 和 Navbar 里的头像、用户名都从这两个 Context 读取；
• OpenContext：管理移动端侧边栏的打开/关闭状态，Navbar 左上角的汉堡按钮和 Sidebar 的关闭按钮共用同一个setOpen。

📌 布局如何生效：路由守卫 + 布局组件

以app/dashboard/page.tsx为例，页面在服务端先查用户，未登录就redirect('/dashboard/signin')，已登录跳转到/dashboard/main。也就是说：

认证逻辑写在"页面层"，布局只负责"长什么样"。

登录页则走另一套骨架——components/auth/AuthUI.tsx提供独立的认证布局（无 Sidebar、无 Navbar），并通过variant属性让同一个 Sidebar 组件在两种布局下表现不同（见下文）。

🗂 Sidebar 源码解析：一个组件，两种形态

核心代码在components/sidebar/Sidebar.tsx（第 44~49 行），关键就三行：

<div className={`lg:!z-99 fixed !z-[99] min-h-full w-[300px] transition-all md:!z-[99] xl:!z-0 ${props.variant === 'auth' ? 'xl:hidden' : 'xl:block'} ${props.open ? '' : '-translate-x-[120%] xl:translate-x-[unset]'}`}>

拆解它的设计思路：

1. 固定宽度 300px +fixed定位：桌面端（xl断点以上）常显，主内容区用xl:ml-[328px]给它让出空间；
2. -translate-x-[120%]位移动画：小屏时整体移出视口，OpenContext的open变为true时滑回，配合transition-all形成抽屉效果，零 JS 动画库；
3. variant === 'auth'双形态：登录页布局传入variant="auth"，xl:hidden直接隐藏侧边栏，同一份代码复用两种场景。

Sidebar 内部自上而下分四个区块（第 60~128 行）：

• 品牌区：Logo + "Horizon AI" 标题 + FREE 徽标；
• 导航菜单：交给子组件components/sidebar/components/Links.tsx渲染；
• 升级卡片：SidebarCard.tsx推广付费版，是模板的变现位；
• 用户信息条：头像、昵称 + 退出登录按钮，数据全部来自 UserContext。

Sidebar 内部结构 ├─ 品牌区（Logo + Badge） ├─ <Links routes={routes} /> ← 数据驱动的导航 ├─ <SidebarCard /> ← 推广卡 └─ 用户信息条（Avatar + 退出）

🔗 导航数据驱动：routes.tsx 是"菜单的配置中心"

Sidebar 自己硬编码了几个菜单项吗？没有。菜单数据全部来自components/routes.tsx（第 14~89 行）：

export const routes: IRoute[] = [ { name: 'Main Dashboard', path: '/dashboard/main', icon: <HiOutlineHome />, collapse: false }, { name: 'AI Chat', path: '/dashboard/ai-chat', icon: <HiOutlineCpuChip />, collapse: false }, ... ];

每个菜单项就是一个{ name, path, icon, disabled }对象。Links.tsx用usePathname()做pathname.includes(route.path)判断高亮（第 20~25 行），disabled: true的项渲染为半透明不可点击样式——加一个页面 = 在数组里加一行，不用碰任何组件。

utils/navigation.tsx的getActiveRoute()用同样的路由表做递归匹配（第 5~18 行），把当前页面的name取出来——这正是 Navbar 标题的来源。

🧭 Navbar 源码解析：悬浮毛玻璃导航条

Navbar 代码在components/navbar/NavbarAdmin.tsx，设计上有三个亮点：

1. 悬浮定位 + 毛玻璃（第 15 行）：fixed定位在顶部，bg-white/30 backdrop-blur-xl实现毛玻璃质感，宽度用calc(100vw - 365px)随断点动态扣掉 Sidebar 占位，实现"漂浮在内容之上"的效果；
2. 面包屑标题数据来自路由表：DashboardLayout 传入brandText={getActiveRoute(routes, pathname)}，导航栏自动显示Pages / AI Chat，无需每页手动写标题；
3. 功能键全部下沉到NavbarLinksAdmin.tsx：

NavbarLinksAdmin 的按钮组（从左到右） ├─ ☰ 汉堡按钮（仅小屏，控制 OpenContext 打开 Sidebar） ├─ 🌙 主题切换（next-themes，light/dark 一键切换） ├─ ⓘ 帮助下拉菜单（DropdownMenu） ├─ ↪ 退出登录（supabase.auth.signOut） └─ 用户头像（点击进设置页）

主题切换按钮只是setTheme(theme === 'dark' ? 'light' : 'dark')一行调用，背后依赖第一层根布局里挂好的 ThemeProvider——三层架构各司其职的典型体现。

🚀 快速上手：5 分钟跑起来

git clone https://gitcode.com/gh_mirrors/sh/shadcn-nextjs-boilerplate cd shadcn-nextjs-boilerplate npm install npm run dev

跑通后建议按这条路径改造成你自己的项目：

1. 换品牌：改components/sidebar/Sidebar.tsx里的 "Horizon AI" 文字与 Logo；
2. 改菜单：编辑components/routes.tsx，增删routes数组项；
3. 换页面：在app/dashboard/下新建目录，参照app/dashboard/main/page.tsx写页面，内容区套上InnerContent即可自动居中限宽；
4. 接认证：登录/注册 UI 在components/auth/AuthUI.tsx，数据库表结构见schema.sql。

✅ 总结：这套布局体系最值得抄的 3 个点

设计点	实现方式	文件
数据驱动导航	菜单 = 一个 TS 数组，组件只负责渲染	components/routes.tsx
无动画库的抽屉侧边栏	CSStranslate-x+ Context 开关	components/sidebar/Sidebar.tsx
布局与认证解耦	页面层做redirect，布局层只管结构	app/dashboard/page.tsx

对新手来说，这个项目最大的价值不是 UI 好看，而是把"一个生产级后台的骨架"拆成了可独立理解的模块：根布局管全局状态、DashboardLayout 管页面骨架、路由表管菜单——读懂这三层，你就掌握了 90% 的 Next.js 后台项目的布局套路。

【免费下载链接】shadcn-nextjs-boilerplateShadcn UI NextJS Boilerplate ⚡️ Free Open-source ChatGPT UI Admin Dashboard Template - Horizon AI Boilerplate项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-nextjs-boilerplate