企业官网建设流程全解析

shadcn-dashboard-landing-template 是一个基于 Vite + React 和 Next.js 双框架、结合 Tailwind CSS 与 Shadcn/UI 的免费开源 Admin 后台 + Landing 落地页模板，内含 30+ 个生产级页面。本文带你完整看懂 shadcn dashboard 模板的项目结构：双版本架构为什么这样设计、每个目录承担什么职责、路由与导入约定有哪些坑，帮助你在动手改造前就建立清晰的全局地图 🗺️。

1. 根目录总览：一仓两版本，文档独立存放

整个仓库顶层只有三个核心目录，职责划分非常干净：

shadcn-dashboard-landing-template/ ├── vite-version/ # Vite + React + React Router 版本 ├── nextjs-version/ # Next.js 15 + App Router 版本 └── docs/ # 独立文档站（指南、组件说明）

两个版本功能完全对等：同样的 30+ 页面、同样的主题自定义器、同样的组件库，区别只在于构建工具与路由机制。这种"平行双版本"架构是理解整个项目结构的第一把钥匙，官方在 docs/guide/project-structure.md 中给出了简明说明。

2. 双版本架构设计：为什么是 Vite + Next.js 并存？

• 选 Vite：内部工具、纯后台管理、追求最快开发迭代、静态托管即可部署的项目。
• 选 Next.js：营销官网 + 后台一体、SEO 敏感、需要 SSR/SSG 或 API 能力的企业级项目。

官方对比与选型决策矩阵详见 docs/guide/choosing-framework.md。不确定的话，建议从 Vite 版本入手，之后再迁移（两者共享层几乎一致，迁移成本低）。

3. Vite 版本目录设计：配置式路由 + 懒加载页面

以 vite-version/src 为核心的目录结构如下：

vite-version/ ├── index.html # SPA 入口 HTML（含字体、SEO meta） ├── vite.config.ts # 构建配置：@ 别名在此定义 └── src/ ├── App.tsx # 应用根组件：Router + ThemeProvider ├── main.tsx # 启动入口 ├── index.css # Tailwind v4 + CSS 变量主题 ├── config/routes.tsx # 全部路由集中声明（懒加载） ├── app/ # 页面层：dashboard、mail、tasks、chat、settings… ├── components/ # 组件层：ui/、layouts/、theme-customizer/ ├── hooks/ # 自定义 Hooks（use-theme、use-sidebar-config…） ├── contexts/ # React Context（主题、侧边栏配置） ├── lib/ # 工具函数（utils.ts、fonts.ts） ├── types/ # TypeScript 类型定义 └── utils/ # 主题预设、analytics 等

3.1 路由设计：所有路由集中在一处

Vite 版本没有用文件路由，而是把全部 30+ 路由集中在 src/config/routes.tsx 中，用React.lazy懒加载每个页面：

const Dashboard = lazy(() => import('@/app/dashboard/page')) const Mail = lazy(() => import('@/app/mail/page'))

路由数组再被 src/components/router/app-router.tsx 递归渲染成 React Router 的<Routes>，并自动套上<Suspense>加载态。这种设计的最大好处是：新增一个页面只需两步——在src/app/下建文件夹写page.tsx，再在routes.tsx注册一行。

3.2 应用启动链路：看懂 App.tsx 就懂了全局

vite-version/src/App.tsx 只有 30 行，却揭示了项目的组装方式：

1. ThemeProvider包裹全局 → 主题切换能力；
2. SidebarConfigProvider→ 侧边栏布局配置（Context 模式）；
3. Router basename支持部署到子路径；
4. AppRouter负责渲染所有路由。

4. Next.js 版本目录设计：文件路由 + 路由组

Next.js 版本的路由完全由src/app/目录结构决定，且用路由组（带括号的文件夹）来组织布局：

nextjs-version/src/app/ ├── (auth)/ # 认证路由组：sign-in、sign-up、forgot-password ├── (dashboard)/ # 后台路由组：dashboard、mail、tasks、chat、settings… │ └── layout.tsx # 后台专属布局（侧边栏等） ├── landing/ # 落地页（独立导航与页脚） ├── layout.tsx # 根布局 ├── loading.tsx # 全局加载组件 ├── not-found.tsx # 404 页面 └── page.tsx # 首页（重定向入口）

关键差异点：

• 路由组：(auth)/与(dashboard)/只影响代码组织，不出现在 URL 中，因此认证页是独立的极简布局，后台页共享侧边栏布局；
• 中间件：src/middleware.ts 负责/login→/auth/sign-in等 URL 重定向，是 Vite 版本没有的服务端能力；
• 框架级优化：next.config.ts 中配置了图片优化（WebP/AVIF）、安全响应头和 SEO 重定向，这些能力 Vite 版本需要自行补齐。

5. 文件命名与导入约定：两版本通用

这是跨版本协作时最重要的部分——两个版本的src/内部约定完全一致，所以组件可以近乎零成本地互相拷贝。

5.1 文件命名规范

💡 演示数据采用就近放置策略：每个功能目录内自带data/文件夹（如 calendars.json），删功能时连数据一起删，互不牵连。

5.2 导入别名（Import Alias）约定

两个版本都把src/注册为@别名，分别定义在 vite-version/vite.config.ts 与 nextjs-version/tsconfig.json 的paths中：

{ "@/*": ["./src/*"] }

再配合 shadcn/ui 的 components.json 别名配置，项目内统一遵循这套导入前缀：

• @/components→ UI 与业务组件（shadcn/ui 组件在@/components/ui）
• @/hooks→ 自定义 Hooks
• @/lib/utils→ 通用工具函数
• @/config、@/types、@/contexts→ 配置、类型与上下文

6. 共享层目录：components、hooks 与 config 是"可移植资产"

真正决定项目可维护性的是共享层目录，它们是两版本间"100% 功能对等"的载体：

• src/components/ui/：shadcn/ui v3 全部基础组件（button、dialog、table、chart 等 40+ 个），Radix UI 打底，样式全部走 Tailwind CSS v4 变量；
• src/components/theme-customizer/：基于 tweakcn 的实时主题编辑器，支持颜色、布局实时预览与导出；
• src/components/layouts/与 app-sidebar.tsx、site-header.tsx：后台骨架（侧边栏 + 顶栏）；
• src/hooks/：use-theme、use-sidebar-config、use-fullscreen等，把交互逻辑从组件中剥离；
• src/config/theme-data.ts：主题预设数据，自定义主题只需在这里追加配置。

主题系统（CSS 变量 + Tailwind v4 的@theme映射）的完整原理可阅读 docs/guide/theme-system.md。

7. 版本间迁移：只动"外壳"，共享层原样复制

由于共享层约定一致，官方给出的迁移路径很简单（见 docs/guide/choosing-framework.md 的 Migration 章节）：

1. 直接复制src/components、src/lib、src/hooks三个目录；
2. Vite → Next.js：把config/routes.tsx的路由改写成app/下的文件夹结构；
3. Next.js → Vite：补一个 React Router 配置即可；
4. 字体加载按各自方式调整（Vite 用 HTML<link>，Next.js 用next/font）。

8. 结构要点速查清单 ✅

• 顶层三目录：vite-version/nextjs-version/docs，先选版本，再深入 src
• Vite 版路由集中在 config/routes.tsx，Next.js 版路由即文件夹
• 页面 = 文件夹 +page.tsx，演示数据就近放在页面目录的data/下
• 一切导入走@/别名，shadcn/ui 组件固定在@/components/ui
• 共享层（components、hooks、lib、config）可跨版本直接复用
• 详细指南：项目结构文档、框架选型指南、功能清单

掌握以上结构后，无论增删页面、扩展主题，还是从 Vite 迁往 Next.js，你都能准确定位到该改动的目录，真正做到"改得动、找得到、删得掉" 🚀。