项目完全指南

Next.js 16.2.9

基于 React 的全栈 Web 框架。提供路由、渲染、优化等一整套方案。

• ▸使用 Turbopack（Rust 编写）作为打包工具，开发时编译极快
• ▸支持 App Router（推荐）和 Pages Router 两种路由模式
• ▸内置图片优化、字体优化、代码分割
• ▸`npm run dev` → 启动开发服务器（热更新）
• ▸`npm run build` → 构建生产版本

React 19.2.4

用户界面（UI）构建库。一切页面都是由 React 组件组成的。

• ▸支持 Server Components（默认）和 Client Components（需 'use client'）
• ▸Server Components 在服务器运行，不发 JS 到浏览器
• ▸Client Components 在浏览器运行，支持交互和状态

TypeScript 5

带类型系统的 JavaScript。写代码时就能发现错误。

• ▸`.tsx` 文件 = TypeScript + JSX（组件文件）
• ▸`.ts` 文件 = 纯 TypeScript（工具 / 数据文件）
• ▸interface 定义数据结构，export/import 共享代码

Tailwind CSS v4

原子化 CSS 框架。直接在 HTML 中用 class 写样式。

• ▸无需单独写 .css 文件，样式直接写在 JSX 的 className 中
• ▸dark: 前缀实现暗色模式（如 dark:bg-black）
• ▸sm:/md:/lg: 前缀实现响应式（移动端 → 桌面端）
• ▸v4 使用 @import 'tailwindcss' 导入，自动移除未用样式

①路由 = 文件夹

②page.tsx = 一个网址的页面内容

③layout.tsx = 所有页面的外壳

④Server Component vs Client Component

⑤Tailwind 暗色模式怎么工作

⑥数据流：从 `_data.ts` 到页面

项目的门面。展示 Next.js Logo、欢迎文字和两个按钮（关于 Next.js / 官方文档）。使用了 next/image 组件优化图片加载。

详细介绍 Next.js 的各项特性。页面用 2×3 的卡片网格展示 6 大核心特性，下半部分用列表展示关键概念（附带链接跳转官方文档），底部有一个终端风格的快速开始代码块。

展示 4 篇博客文章卡片，2×2 网格布局。每张卡片包含 emoji 封面、分类标签、日期、标题、摘要和阅读时长。卡片 hover 时有阴影效果，点击进入文章详情页。

动态路由页面。URL 中的 [slug] 会被替换为真实文章名。页面顶部显示分类标签+日期+时长，中间是完整的文章正文（支持标题、段落和代码块渲染），底部有返回博客的导航。

一个 Route Handler（路由处理器）。导出一个 async GET() 函数，Next.js 自动把 /api/hello 映射给它。用 new Date() 获取服务器时间，通过 NextResponse.json() 返回日期、时间、时区、Unix 时间戳等数据。

async Server Component。在服务端通过 fetch('/api/hello') 调用自己的 API，拿到数据后渲染为 HTML。整个数据流转在服务端完成，浏览器收到的是带完整数据的页面。

演示 16 个 shadcn/ui 组件（Button、Card、Dialog、Tabs、Table 等）。这是一份互动式「组件目录」，每个组件都有可点击的实例，你可以直接看到它们长什么样，然后复制到自己的页面中使用。

就是你现在看的这一页！一份写给新手的完整说明书。

当用户访问不存在的网址时，Next.js 自动显示这个 404 页面。包含友好的提示文案和返回首页的按钮。

shadcn/ui 不是一个 npm 包。它是一套可以直接 复制到项目中的、基于 Base UI（Radix UI 的精神继承者）+ Tailwind CSS 构建的组件集合。和 MUI、Ant Design 不同—— 你拥有组件的全部源代码，随时可以直接修改。

• ▸组件源码在你的项目中（components/ui/），完全掌控
• ▸底层使用 Base UI（@base-ui/react）提供无障碍和交互逻辑
• ▸样式靠 Tailwind CSS + CSS 变量（在 globals.css 中定义）
• ▸通过 npx shadcn@latest add <组件名> 命令安装
• ▸图标库使用 lucide-react（1000+ SVG 图标）

除了安装组件，我们还创建了 app/shadcn/page.tsx（组件展示页）和 修改了导航栏，让所有组件可以被直观地浏览和测试：

• ▸app/shadcn/page.tsx — 展示页（"use client"），按编号展示 9 大组件区块
• ▸每个区块都是可互动的真实示例（按钮可点击、表单可提交、弹窗可打开）
• ▸表单示例使用 useState 管理状态，提交后通过 Sonner 弹出通知
• ▸app/_components/Nav.tsx — 新增 { href: '/shadcn', label: '组件' }

只需要 3 步，和用普通 React 组件完全一样：

Next.js DevTools 是框架内置的开发辅助工具。它会在开发 模式下的浏览器页面中自动显示一个悬浮图标，不需要安装任何浏览器插件或 npm 包——只要你运行了 npm run dev，它就会出现。

它是通过一个独立的 JavaScript 脚本（next-devtools）加载的， 在生成的 HTML 中你可以看到类似这样的引用：

这个脚本只在开发模式下加载，生产构建（npm run build） 后不会包含，所以你的真实用户永远看不到它。

默认情况下，它出现在左下角。你可以通过 next.config.ts 中的 devIndicators 选项来 调整位置或完全隐藏它：

• ▸由 Next.js 编译器在 dev 模式下自动注入 next-devtools 脚本
• ▸通过 Turbopack HMR（热模块替换）WebSocket 实时接收编译状态
• ▸底层使用 React 渲染 UI，和你的应用共享同一个 React 实例
• ▸生产构建（next build）时，devIndicators 相关代码完全不会被打包
• ▸它的核心职责是「开发体验」——让你在写代码时获得即时反馈

在 App Router 中，Route Handler 用 route.ts 文件定义。只需导出一个以 HTTP 方法命名的 函数（如 GET、POST）， Next.js 就会自动将对应的请求路由到该函数。

本项目的 API 文件结构：

这个 API 做的事情非常直观：

• ▸用 new Date() 获取服务器的当前时间
• ▸格式化为中文日期（2026年6月13日星期六）
• ▸格式化为 24 小时制时间（11:10:01）
• ▸获取服务器时区（Asia/Shanghai）
• ▸计算 Unix 时间戳
• ▸返回 Node.js 版本、操作系统、CPU 架构等环境信息
• ▸通过 NextResponse.json() 将所有数据打包为 JSON 返回

这是一个 async Server Component。它本身在服务端 运行，在渲染 HTML 之前先通过 fetch 调用自己的 API 获取数据，然后把数据填充到页面中。浏览器收到的是已经包含完整数据的 静态 HTML，不需要任何客户端 JavaScript。

页面展示了以下内容：

• ▸4 张数据卡片：日期、时间、时区、Unix 时间戳、UTC 时间
• ▸服务器环境信息：Node.js 版本、操作系统、CPU 架构
• ▸技术说明：解释 API → 页面 → 数据流转的完整链路
• ▸刷新按钮：重新请求页面即可获取最新时间
• ▸错误处理：API 不可用时显示友好提示而非报错

这 6 步全部在服务端完成。用户浏览器只发起一次 HTTP 请求，收到的就是一个已经包含所有数据的完整页面。这就是 Next.js "全栈框架" 的核心价值——前端和后端在同一个项目中协作，不需要分开部署。

1在浏览器访问 http://localhost:3000/api/hello，看到 JSON 原始数据
2访问 /server-demo，看到用这些 JSON 数据渲染的漂亮页面
3多次刷新 /server-demo，时间会实时更新（因为使用了 cache: 'no-store'）
4在终端中 curl http://localhost:3000/api/hello，体验命令行调用 API
5尝试修改 route.ts 中的返回数据，刷新页面看变化（dev 模式热更新）