如何设置一个新的 Next.js 项目
系统要求
在开始之前,请确保你的系统满足以下要求:
- Node.js 18.18 或更高版本。
- macOS、Windows(包括 WSL)或 Linux。
自动安装
创建新的 Next.js 应用最快捷的方式是使用 create-next-app
,它会为你自动设置好所有内容。要创建一个项目,请运行:
npx create-next-app@latest
在安装过程中,你将看到以下提示:
What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack for `next dev`? No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*
完成提示后,create-next-app
将创建一个以你的项目名命名的文件夹并安装所需的依赖。
手动安装
要手动创建一个新的 Next.js 应用,请安装所需的包:
npm install next@latest react@latest react-dom@latest
然后,在你的 package.json
文件中添加以下脚本:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
}
}
这些脚本对应于开发应用程序的不同阶段:
next dev
:启动开发服务器。next build
:构建用于生产环境的应用程序。next start
:启动生产服务器。next lint
:运行 ESLint。
创建 app
目录
Next.js 使用文件系统路由,这意味着应用程序中的路由由你的文件结构决定。
创建一个 app
文件夹。然后,在 app
内创建一个 layout.tsx
文件。这个文件是根布局。它是必需的,并且必须包含 <html>
和 <body>
标签。
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
创建一个带有初始内容的主页 app/page.tsx
:
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
当用户访问你的应用程序根目录(/
)时,layout.tsx
和 page.tsx
都将被渲染。
值得注意的是:
- 如果你忘记创建根布局,Next.js 会在使用
next dev
运行开发服务器时自动创建这个文件。- 你可以选择在项目根目录中使用
src
目录,以将应用程序代码与配置文件分开。
创建 public
文件夹(可选)
在项目根目录创建一个 public
文件夹,用于存储静态资源,如图片、字体等。public
中的文件可以从基础 URL(/
)开始被你的代码引用。
你可以使用根路径(/
)引用这些资源。例如,public/profile.png
可以被引用为 /profile.png
:
import Image from 'next/image'
export default function Page() {
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}
运行开发服务器
- 运行
npm run dev
启动开发服务器。 - 访问
http://localhost:3000
查看你的应用程序。 - 编辑
app/page.tsx
文件并保存,在浏览器中查看更新后的结果。
设置 TypeScript
最低 TypeScript 版本:
v4.5.2
Next.js 内置了 TypeScript 支持。要将 TypeScript 添加到你的项目中,将文件重命名为 .ts
/ .tsx
并运行 next dev
。Next.js 将自动安装必要的依赖项并添加一个具有推荐配置选项的 tsconfig.json
文件。
IDE 插件
Next.js 包含一个自定义 TypeScript 插件和类型检查器,VSCode 和其他代码编辑器可以使用它进行高级类型检查和自动完成。
你可以通过以下方式在 VS Code 中启用该插件:
- 打开命令面板(
Ctrl/⌘
+Shift
+P
) - 搜索 "TypeScript: Select TypeScript Version"
- 选择 "Use Workspace Version"
有关更多信息,请参阅 TypeScript 参考页面。
设置 ESLint
Next.js 内置了 ESLint。当你使用 create-next-app
创建新项目时,它会自动安装必要的包并配置适当的设置。
要手动将 ESLint 添加到现有项目中,请在 package.json
中添加 next lint
作为脚本:
{
"scripts": {
"lint": "next lint"
}
}
然后,运行 npm run lint
,你将被引导完成安装和配置过程。
npm run lint
你会看到如下提示:
? How would you like to configure ESLint?
❯ Strict (recommended)
Base
Cancel
- Strict:包括 Next.js 的基本 ESLint 配置以及更严格的 Core Web Vitals 规则集。这是首次设置 ESLint 的开发人员的推荐配置。
- Base:包括 Next.js 的基本 ESLint 配置。
- Cancel:跳过配置。如果你计划设置自己的自定义 ESLint 配置,请选择此选项。
如果选择了 Strict
或 Base
,Next.js 将自动安装 eslint
和 eslint-config-next
作为应用程序的依赖项,并在项目根目录创建一个包含所选配置的 .eslintrc.json
文件。
现在,每当你想运行 ESLint 来捕获错误时,都可以运行 next lint
。设置 ESLint 后,它还会在每次构建(next build
)期间自动运行。错误将导致构建失败,而警告则不会。
有关更多信息,请参阅 ESLint 插件页面。
设置绝对导入和模块路径别名
Next.js 内置支持 tsconfig.json
和 jsconfig.json
文件的 "paths"
和 "baseUrl"
选项。
这些选项允许你将项目目录别名为绝对路径,使模块导入更简单、更清晰。例如:
// Before
import { Button } from '../../../components/button'
// After
import { Button } from '@/components/button'
要配置绝对导入,请在 tsconfig.json
或 jsconfig.json
文件中添加 baseUrl
配置选项。例如:
{
"compilerOptions": {
"baseUrl": "src/"
}
}
除了配置 baseUrl
路径外,你还可以使用 "paths"
选项来 "alias"
模块路径。
例如,以下配置将 @/components/*
映射到 components/*
:
{
"compilerOptions": {
"baseUrl": "src/",
"paths": {
"@/styles/*": ["styles/*"],
"@/components/*": ["components/*"]
}
}
}
每个 "paths"
都相对于 baseUrl
位置。