创建新的 Next.js 应用
系统要求
- Node.js 18.18 或更高版本。
- 支持 macOS、Windows(包括 WSL)和 Linux。
自动安装
我们建议使用 create-next-app
来开始一个新的 Next.js 应用,它会为你自动设置好一切。要创建一个项目,请运行:
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
:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
}
}
这些脚本对应应用程序开发的不同阶段:
dev
:运行next dev
以开发模式启动 Next.js。build
:运行next build
为生产环境构建应用程序。start
:运行next start
启动 Next.js 生产服务器。lint
:运行next lint
设置 Next.js 内置的 ESLint 配置。
创建 pages
目录
Next.js 使用文件系统路由,这意味着应用程序中的路由取决于你的文件结构。
在项目根目录创建一个 pages
目录。然后,在 pages
文件夹内添加一个 index.tsx
文件。这将是你的首页(/
):
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
接下来,在 pages/
中添加一个 _app.tsx
文件来定义全局布局。了解更多关于自定义 App 文件的信息。
import type { AppProps } from 'next/app'
export default function App({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />
}
最后,在 pages/
中添加一个 _document.tsx
文件来控制服务器的初始响应。了解更多关于自定义 Document 文件的信息。
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
创建 public
文件夹(可选)
你可以选择在项目根目录创建一个 public
文件夹,用于存储静态资源,如图片、字体等。public
中的文件可以从基本 URL(/
)开始被你的代码引用。
运行开发服务器
- 运行
npm run dev
启动开发服务器。 - 访问
http://localhost:3000
查看你的应用程序。 - 编辑
pages/index.tsx
文件并保存,在浏览器中查看更新后的结果。
设置 TypeScript
最低 TypeScript 版本:
v4.5.2
Next.js 内置了 TypeScript 支持。要将 TypeScript 添加到你的项目中,只需将文件重命名为 .ts
/ .tsx
。运行 next dev
时,Next.js 将自动安装必要的依赖项,并添加带有推荐配置选项的 tsconfig.json
文件。
查看 TypeScript 配置页面,了解更多关于如何在项目中使用 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 配置以及更严格的核心 Web Vitals 规则集。这是首次设置 ESLint 的开发者的推荐配置。
- Base:包括 Next.js 的基本 ESLint 配置。
- Cancel:不包括任何 ESLint 配置。仅在你计划设置自己的自定义 ESLint 配置时选择此选项。
如果选择了前两个配置选项中的任何一个,Next.js 将自动在你的应用程序中安装 eslint
和 eslint-config-next
作为依赖项,并在项目根目录中创建一个包含所选配置的 .eslintrc.json
文件。
现在,你可以在每次想要运行 ESLint 以捕获错误时运行 next lint
。设置 ESLint 后,它还会在每次构建(next build
)期间自动运行。错误将导致构建失败,而警告则不会。
查看 ESLint 插件页面,了解更多关于如何在项目中配置 ESLint 的信息。
设置绝对导入和模块路径别名
Next.js 内置支持 tsconfig.json
和 jsconfig.json
文件的 "paths"
和 "baseUrl"
选项。这些选项允许你将项目目录别名为绝对路径,使导入模块更容易。例如:
// 之前
import { Button } from '../../../components/button'
// 之后
import { Button } from '@/components/button'
要配置绝对导入,请在 tsconfig.json
或 jsconfig.json
文件中添加 baseUrl
配置选项。例如:
{
"compilerOptions": {
"baseUrl": "src/"
}
}
除了配置 baseUrl
路径外,你还可以使用 "paths"
选项来为模块路径创建"别名"。
例如,以下配置将 @/components/*
映射到 components/*
:
{
"compilerOptions": {
"baseUrl": "src/",
"paths": {
"@/styles/*": ["styles/*"],
"@/components/*": ["components/*"]
}
}
}
每个 "paths"
都相对于 baseUrl
位置。例如:
import Button from '@/components/button'
import '@/styles/styles.css'
export default function HomePage() {
return (
<div>
<h1>Hello World</h1>
<Button />
</div>
)
}