入门指南

创建新项目

我们推荐使用 pnpm 作为包管理工具，因为它比 npm 或 yarn 更快更高效。如果尚未安装 pnpm，可通过以下命令全局安装：

npm install -g pnpm

要创建 Next.js 应用，请打开终端，cd 进入项目存放目录，然后运行以下命令：

npx create-next-app@latest nextjs-dashboard --example "https://github.com/vercel/next-learn/tree/main/dashboard/starter-example" --use-pnpm

此命令使用了 create-next-app —— 一个用于快速搭建 Next.js 应用的命令行工具 (CLI)。命令中的 --example 参数指定了本课程的初始示例项目。

浏览项目结构

与其他从零开始编写代码的教程不同，本课程的大部分代码已预先完成。这更贴近实际开发场景，您通常会基于现有代码库进行开发。

我们的目标是让您专注于学习 Next.js 的核心功能，而无需编写所有应用代码。

安装完成后，在代码编辑器中打开项目并进入 nextjs-dashboard 目录：

cd nextjs-dashboard

让我们先熟悉项目结构。

文件夹结构

项目包含以下目录结构：

• /app：包含应用的所有路由、组件和逻辑，这是您主要的工作目录
• /app/lib：包含应用使用的函数，如可复用的工具函数和数据获取函数
• /app/ui：包含所有 UI 组件（如卡片、表格和表单），这些组件已预先完成样式设计
• /public：包含静态资源文件（如图片）
• 配置文件：根目录下的 next.config.ts 等配置文件，这些文件由 create-next-app 自动生成并预配置，本课程中无需修改

您可以自由浏览这些目录，暂时无需理解所有代码的实现细节。

占位数据

构建用户界面时，占位数据非常有用。如果数据库或 API 尚未就绪，您可以：

• 使用 JSON 格式或 JavaScript 对象作为占位数据
• 使用第三方服务如 mockAPI

本项目已在 app/lib/placeholder-data.ts 中提供了占位数据。文件中的每个 JavaScript 对象代表数据库中的一个表。例如发票表的数据：

const invoices = [
  {
    customer_id: customers[0].id,
    amount: 15795,
    status: 'pending',
    date: '2022-12-06',
  },
  {
    customer_id: customers[1].id,
    amount: 20348,
    status: 'pending',
    date: '2022-11-14',
  },
  // ...
];

在设置数据库章节，您将使用这些数据进行数据库初始化 (seed)。

TypeScript

您可能注意到大多数文件使用 .ts 或 .tsx 后缀。这是因为项目采用 TypeScript 编写，以反映现代开发生态。

即使不熟悉 TypeScript 也没关系 —— 我们会提供所需的 TypeScript 代码片段。

现在可以查看 /app/lib/definitions.ts 文件。这里我们手动定义了数据库返回的类型。例如发票表的类型定义：

export type Invoice = {
  id: string;
  customer_id: string;
  amount: number;
  date: string;
  // TypeScript 中的字符串联合类型
  // 表示 status 属性只能是 'pending' 或 'paid' 之一
  status: 'pending' | 'paid';
};

使用 TypeScript 可以避免错误的数据传递，例如向发票金额 (amount) 传递字符串而非数字。

TypeScript 开发者请注意：

• 虽然我们手动声明了数据类型，但为了更好的类型安全，推荐使用 Prisma 或 Drizzle，它们能根据数据库模式自动生成类型
• Next.js 会自动检测项目是否使用 TypeScript 并安装必要的包和配置。Next.js 还提供了TypeScript 插件来增强编辑器自动补全和类型安全

启动开发服务器

首先运行 pnpm i 安装项目依赖：

pnpm i

然后运行 pnpm dev 启动开发服务器：

pnpm dev

pnpm dev 会在 3000 端口启动 Next.js 开发服务器。访问以下地址检查是否运行成功：

打开浏览器访问 http://localhost:3000，您将看到如下未应用样式的首页（这是有意为之）：