shadcn-ui/taxonomy：Next.js 13 全栈能力的全景式实验场

背景：一个关于"实验"的实验

2022 年 Next.js 13 发布时，其全新 App Router 和 React Server Components 特性彻底颠覆了 React 应用的渲染模型。shadcn 本人在彼时启动了 taxonomy 项目——一个"实验性参考应用"，目的是在 Next.js 13 仍处于公开预览阶段时，亲手摸清这套新架构的边界在哪里。

这个项目后来成了整个 shadcn 生态的一面旗帜。它不是一个组件库，也不是一个模板，而是一份活的全栈实践报告。开发者可以通过它看到：当认证、数据库、支付、内容管理这些真实需求落地时，Server Components 和 Client Components 之间应该如何划分边界，Route Handlers 如何承接 API 请求，Middleware 如何处理全局拦截。

2026 年，shadcn 官方宣布 taxonomy 项目正式归档（Archived），理由是 Next.js 框架已经稳定成熟，而项目代码未能及时跟进演进，不再代表最新最佳实践。这本身就是一个值得记录的技术判断。

核心功能：五大模块覆盖全栈需求

taxonomy 的目录结构经过精心设计，分为五大功能模块：

营销模块（/marketing）：面向访客的首页、Landing Pages、产品介绍等落地页，展示完整的 Tailwind CSS 响应式布局能力，暗色模式支持，以及 MDX 内容渲染。

文档模块（/docs）：基于 Contentlayer 构建的技术文档站，支持 MDX 富文本格式，提供导航层级和搜索能力。是将 shadcn/ui 文档站点能力独立出来的参考实现。

仪表盘模块（/dashboard）：面向登录用户的个人控制台，展示账单信息、订阅状态和账户管理界面。集成 Stripe 订阅管理，让用户直观看到不同订阅层级的功能差异。

编辑器模块（/editor）：基于 Editor.js 构建的富文本编辑器，支持代码块、嵌入媒体、表格等复杂内容创作。是 shadcn 生态中文档创作工具链的典型集成方式。

API 路由（/api）：Next.js Route Handlers 处理认证回调、Webhook 推送等后端逻辑，与 NextAuth 和 Stripe 形成闭环。

技术架构：Server Components 的边界实验

taxonomy 的技术选型本身就是一份教学材料：

Middleware 层（middleware.ts）展示了如何在 Next.js 层面做全局认证拦截和路由守卫——未登录用户访问 /dashboard 时会被重定向到登录页，所有请求在到达 Server Components 之前完成身份校验。

Prisma Schema 定义了 User、Account、Session 等核心模型，与 NextAuth 的 Adapter 模式紧密配合，展示了如何将认证状态持久化到自定义数据库而非平台托管方案。

⚠️ 重要警告：项目已归档

这是 taxonomy 与其他参考项目最大的不同点。README 开篇即注明：

"This project has been officially archived and will no longer receive updates."

具体含义：

• 代码不再更新，不反映当前 Next.js 最佳实践
• 可能包含已废弃的 API 和模式
• 不建议用于生产环境

但作为学习 Next.js 13 新特性的教材，taxonomy 的参考价值并未消失。它的核心价值在于展示了一个完整全栈应用的结构思路——如何组织目录、如何划分 Server/Client 边界、如何在 Server Components 中处理数据获取。这些思路不因框架版本迭代而完全失效。

部署体验

taxonomy 没有提供 Dockerfile 或 docker-compose，但作为标准 Next.js 应用，部署路径非常清晰：

本地开发：pnpm install → 配置 .env.local（参考 .env.example）→ pnpm dev。两个关键依赖需要额外注意：prisma generate（通过 postinstall 自动执行）和 contentlayer dev（与 Next.js 并行启动）。

Vercel 部署：该项目的作者 shadcn 本身就是 Vercel 的合作伙伴，Vercel 是默认推荐的部署目标。在 Vercel 控制台导入仓库后，只需配置环境变量即可一键上线。Vercel 内置了 Next.js 优化，几乎不需要额外配置。

环境变量中最关键的是 DATABASE_URL（连接 PlanetScale）和 NEXTAUTH_SECRET（加密会话），缺失会导致认证和数据库功能完全不可用。

局限性

1. 项目已归档：这是最大的局限性。Next.js 14/15 的新特性（如 Server Actions 稳定化、Turbopack 等）在 taxonomy 中完全没有覆盖
2. 依赖版本老旧：package.json 中的 Next.js 版本停留在 13.3.2-canary，与现代稳定版差距较大，直接 pnpm install 可能面临依赖冲突
3. PlanetScale 依赖：数据库层强依赖 PlanetScale（Serverless MySQL），本地开发需要额外配置或使用其他 MySQL 兼容方案替代
4. Stripe 配置复杂度：完整支付流程需要 Stripe 开发者账号和真实测试环境，配置链路较长

总结：不是模板，是路线图

taxonomy 不是那种拿来就能用的启动模板。它的定位更像一份全栈技术路线图——当你想要在 Next.js 13 中实现某个功能时，可以来这里找到对应的参考实现。认证怎么做、数据怎么取、支付怎么接、文档怎么搭，taxonomy 都以最小可用规模展示了完整的实现路径。

即便项目已经归档，它仍然是理解 shadcn 生态和 Next.js App Router 设计理念的重要入口。唯一需要记住的是：代码仅供参考，上线前请确认依赖版本与现代 Next.js 稳定版的兼容性。