NextDevKit 项目架构

全面了解 NextDevKit 的项目结构，从基础的 Next.js 设置到生产级 SaaS 架构的完整指南。

本指南将通过展示从基础 Next.js 项目到完整生产级 NextdevKit SaaS 模板的演进过程，帮助你理解 NextDevKit 的组织方式。每一步都建立在前一步的基础上，让你轻松理解每个架构决策背后的原理。

理解演进过程

NextDevKit 被设计为生产级别的启动模板，这意味着它从一开始就包含了许多功能。然而，了解这个结构是如何演进的可以帮助你：

让我们从头开始，逐步构建到完整的架构。

步骤 1：基础 - Next.js 基础

每个 Next.js 项目都从这些基本文件开始。这是运行 Next.js 应用程序所需的最小设置。

layout.tsx

page.tsx

globals.css

next.config.ts

package.json

tsconfig.json

核心文件：

layout.tsx - 包裹所有页面的根布局（全局页眉、页脚、元数据）
page.tsx - 位于 / 的首页
globals.css - 全局样式和 Tailwind 指令
next.config.ts - Next.js 配置
tsconfig.json - TypeScript 配置

步骤 2：添加基础工具

在构建功能之前，我们添加开发工具和样式基础，以确保代码质量和一致性。

我们可以执行以下命令来添加更多需要的 shadcnui 基础组件：

pnpm dlx shadcn@latest add button input card

layout.tsx

page.tsx

globals.css

button.tsx

input.tsx

card.tsx

utils.ts

biome.json

components.json

next.config.ts

package.json

postcss.config.mjs

tsconfig.json

新增内容：

components/ui/ - shadcn/ui 组件（设计系统基础组件）
lib/utils.ts - 工具函数（cn 辅助函数、格式化器等）
biome.json - 代码格式化和 lint 配置
components.json - shadcn/ui 配置
postcss.config.mjs - Tailwind 的 PostCSS 配置

步骤 3：使用 App Router 组织路由

随着应用程序的增长，我们使用 Next.js App Router 模式来组织路由：路由组和国际化。

layout.tsx

not-found.tsx

架构模式：

[locale]/ - 国际化的动态路由段（例如 /en、/zh）
(marketing)/ - 公共页面的路由组（不影响 URL）
(app)/ - 需要认证页面的路由组
[[...slug]] - 可选的 catch-all 路由，用于灵活路由（文档）
[...slug] - 必需的 catch-all 路由，用于博客文章和法律页面

URL 示例：

/en/pricing → 英文定价页面
/zh/blog/nextdevkit-tech-stack → 中文博客文章
/en/docs/getting-started/overview → 文档页面
/en/credits → 积分定价页面
/auth/login → 登录页面（不需要 locale）
/app/dashboard → 仪表板（受保护的路由）
/app/admin/users → 管理员用户页面
/app/ai/chat → AI 聊天功能

步骤 4：组件架构

除了页面的路由之外，我们还需要组织前端组件样式的文件，以便我们可以更好的复用这些前端组件，所有的前端复用组件都放在 src/components/ 目录下。

前端复用组件文件组织结构：

ui/ - 来自 shadcn/ui 的原始可复用 UI 组件（更多 shadcn/ui 组件...）
auth/ - 认证表单和组件
marketing/ - 按功能组织的落地页和营销组件
dashboard/ - 应用仪表板布局组件示例
settings/ - 按类别组织的用户设置表单（账户、账单、通知、安全、使用情况）
admin/ - 管理面板组件
ai-elements/ - Vercel AI SDK 相关的 UI 组件（对话、消息、代码块等）
shared/ - 跨多个功能共享（页眉、页脚、cookie 等）
docs/ & blog/ - MDX 内容组件
examples/ - 示例实现（AI 聊天、AI 图像生成、仪表板示例）
icons/ - Logo、社交媒体和技术栈图标

步骤 5 内容管理

使用基于 MDX 的内容管理使 APP 易于自定义和维护。用 MDX 来构建博客和文档，并且支持国际化。所有的内容都放在 src/content/ 目录下。

en.json

zh.json

配置结构：

content/ - 博客（8 篇文章）、文档和法律页面的 MDX 内容
i18n/ - 国际化工具
messages/ - 翻译文件（英文和中文）

步骤 6：数据库和认证

数据层和认证系统构成了应用程序的支柱。你需要熟悉 Drizzle ORM 和 Better Auth 的用法来构建你的数据库和认证系统。

数据库 client 和对应的表都放在 src/database/ 目录下。认证相关的文件都放在 src/lib/auth/ 目录下。

auth.ts

utils.ts

metadata.ts

safe-action.ts

source.ts

toc.ts

urls.ts

i18n.ts

drizzle.config.ts

数据库层：

database/client.ts - Drizzle ORM 客户端实例
database/schema.ts - 数据库表和关系（用户、会话、积分、交易等）
drizzle/ - 迁移文件和历史记录

认证系统：

lib/auth.ts - Better Auth 配置
lib/auth/client.ts - 客户端认证工具（useSession、reloadSession）
lib/auth/server.ts - 服务器端认证工具（getSession）
lib/auth/api.ts - API 路由辅助函数
lib/auth/edge.ts - Edge 运行时认证函数
lib/auth/session-context.ts - Session 的 React context
lib/auth/errors.ts - 认证错误处理

支持库：

lib/actions/ - 用于数据变更的服务器操作
lib/hooks/ - 自定义 React hooks
lib/stores/ - 全局状态的 Zustand stores
lib/safe-action.ts - 类型安全的服务器操作包装器
lib/source.ts - Fumadocs 源配置
types/ - 共享的 TypeScript 类型定义

步骤 7：API 路由和服务器函数

后端功能通过 API 路由和服务器操作实现。你需要熟悉 Next.js 的 API 路由，你可以创建新的 /api/**/route.ts 来实现你的 API 路由。

robots.ts

sitemap.ts

middleware.ts

API 路由：

api/auth/[...all]/route.ts - Better Auth API 处理器（catch-all 路由）
api/ai/demo/chat/route.ts - AI 聊天演示端点
api/ai/demo/image/route.ts - AI 图像生成演示端点
api/search/route.ts - 文档搜索功能
api/jobs/credits/expire/route.ts - 定时任务，过期积分
api/jobs/credits/grant/route.ts - 定时任务，授予订阅积分
api/webhooks/stripe/route.ts - Stripe webhook 处理器
api/webhooks/creem/route.ts - Creem webhook 处理器

特殊路由：

image-proxy/[...path]/route.ts - 图片代理以优化
robots.ts - 动态生成 robots.txt
sitemap.ts - 动态生成 sitemap

中间件：

middleware.ts - 路由保护、重定向、国际化

步骤 8：业务逻辑模块

企业功能如 AI、积分、支付、邮件和存储被组织为模块化系统。你需要熟悉这些模块的用法来构建你的业务逻辑。

ai/ - AI 相关的文件都放在 src/ai/ 目录下。
credits/ - 积分相关的文件都放在 src/credits/ 目录下。
payment/ - 支付相关的文件都放在 src/payment/ 目录下。
mail/ - 邮件相关的文件都放在 src/mail/ 目录下。
storage/ - 存储相关的文件都放在 src/storage/ 目录下。

AI 系统：

ai/models/ - AI 模型配置（聊天、图像）
ai/agents/ - AI 代理和工具（天气代理）
ai/image/ - 图像生成工具和 hooks
ai/prompts.ts - 系统提示词和模板
ai/errors.ts - AI 特定的错误处理

积分系统：

credits/actions/ - 积分管理的服务器操作（10+ 个操作文件）
- 消费、授予、过期积分
- 跟踪用户交易
- 处理订阅和购买奖励
credits/types.ts - 积分相关的 TypeScript 类型

支付系统：

payment/actions/ - 支付操作的服务器操作（10 个操作文件）
- 创建结账链接和客户门户
- 处理订阅和一次性付款
- 处理来自支付提供商的 webhooks
payment/providers/ - 支付提供商实现（Stripe、Creem）
payment/types.ts - 支付相关的 TypeScript 类型

邮件系统：