章节1

入门指南

创建新项目

我们建议使用 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，这是一个命令行界面 (CLI) 工具，用于为你设置 Next.js 应用程序。在上面的命令中，你还使用了 --example 标志和本课程的 starter example。

探索项目

与从头开始编写代码的教程不同，本课程的大部分代码已经为你编写好了。这更好地反映了真实世界的开发，在真实世界中，你很可能需要处理现有的代码库。

我们的目标是帮助你专注于学习 Next.js 的主要功能，而无需编写所有应用程序代码。

安装完成后，在你的代码编辑器中打开项目并导航到 nextjs-dashboard。

终端

cd nextjs-dashboard

让我们花一些时间探索项目。

文件夹结构

你会注意到项目具有以下文件夹结构

Folder structure of the dashboard project, showing the main folders and files: app, public, and config files.

/app：包含应用程序的所有路由、组件和逻辑，你将主要在这里工作。
/app/lib：包含应用程序中使用的函数，例如可重用的实用程序函数和数据获取函数。
/app/ui：包含应用程序的所有 UI 组件，例如卡片、表格和表单。为了节省时间，我们已经为你预先设置了这些组件的样式。
/public：包含应用程序的所有静态资源，例如图像。
配置文件：你还会注意到应用程序根目录下的配置文件，例如 next.config.ts。大多数这些文件是在你使用 create-next-app 启动新项目时创建和预先配置的。在本课程中，你无需修改它们。

随意探索这些文件夹，如果你还不了解代码在做什么，请不要担心。

占位符数据

当你构建用户界面时，拥有一些占位符数据会很有帮助。如果数据库或 API 尚不可用，你可以

在 JSON 格式或作为 JavaScript 对象中使用占位符数据。
使用第三方服务，例如 mockAPI。

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

/app/lib/placeholder-data.ts

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',
  },
  // ...
];

在关于设置数据库的章节中，你将使用这些数据填充你的数据库（用一些初始数据填充它）。

TypeScript

你可能还会注意到大多数文件都有 .ts 或 .tsx 后缀。这是因为该项目是用 TypeScript 编写的。我们希望创建一个反映现代 Web 格局的课程。

如果你不了解 TypeScript 也没关系 - 我们将在需要时提供 TypeScript 代码片段。

现在，看一下 /app/lib/definitions.ts 文件。在这里，我们手动定义将从数据库返回的类型。例如，发票表具有以下类型

/app/lib/definitions.ts

export type Invoice = {
  id: string;
  customer_id: string;
  amount: number;
  date: string;
  // In TypeScript, this is called a string union type.
  // It means that the "status" property can only be one of the two strings: 'pending' or 'paid'.
  status: 'pending' | 'paid';
};

通过使用 TypeScript，你可以确保你不会意外地将错误的数据格式传递给你的组件或数据库，例如将 string 而不是 number 传递给发票 amount。

如果你是 TypeScript 开发人员

我们正在手动声明数据类型，但为了更好的类型安全性，我们建议使用 Prisma 或 Drizzle，它们会根据你的数据库模式自动生成类型。

Next.js 会检测你的项目是否使用 TypeScript，并自动安装必要的包和配置。Next.js 还带有一个用于你的代码编辑器的 TypeScript 插件，以帮助实现自动完成和类型安全。

运行开发服务器

运行 pnpm i 以安装项目的包。

终端

pnpm i

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

终端

pnpm dev

pnpm dev 在端口 3000 上启动你的 Next.js 开发服务器。让我们检查一下它是否正在工作。

在你的浏览器上打开 https://127.0.0.1:3000。你的主页应该看起来像这样，它是故意没有样式的

Unstyled page with the title 'Acme', a description, and login link.