本文档由本人在next官网,通过文档学习的形式,翻译而来。
本文档持续跟新中
入门
什么是Next.js
Next.js 是一个用于构建全栈 Web 应用程序的 React 框架。您可以使用 React Components 来构建用户界面,并使用 Next.js 来实现附加功能和优化。
在底层,Next.js 还抽象并自动配置 React 所需的工具,例如捆绑、编译等。这使您可以专注于构建应用程序,而不是花时间进行配置。
无论您是个人开发人员还是大型团队的一员,Next.js 都可以帮助您构建交互式、动态且快速的 React 应用程序。
主要特点
Next.js 的一些主要功能包括:
特征 | 描述 |
---|---|
路由 | 基于文件系统的路由器构建在服务器组件之上,支持布局、嵌套路由、加载状态、错误处理等。 |
渲染 | 使用客户端和服务器组件进行客户端和服务器端渲染。使用 Next.js 在服务器上进一步优化静态和动态渲染。在 Edge 和 Node.js 运行时上进行流式传输。 |
数据获取 | 通过服务器组件中的 async/await 简化数据获取,以及 |
造型 | 支持您喜欢的样式方法,包括 CSS 模块、Tailwind CSS 和 CSS-in-JS |
优化 | 图像、字体和脚本优化,以改善应用程序的核心网络生命和用户体验。 |
TypeScript | 改进了对 TypeScript 的支持,提供更好的类型检查和更高效的编译,以及自定义 TypeScript 插件和类型检查器。 |
应用程序路由于页面路由
Next.js 有两个不同的路由器:App Router 和 Pages Router。App Router 是一个较新的路由器,允许您使用 React 的最新功能,例如服务器组件和流媒体。Pages Router 是原始的 Next.js 路由器,它允许您构建服务器渲染的 React 应用程序,并继续支持旧版 Next.js 应用程序。
安装
系统要求
Node.js 18.17或更新版本
支持 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 to use `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to customize the default import alias (@/*)? 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 配置。
创建目录
Next.js 使用文件系统路由,这意味着应用程序中的路由由您构建文件的方式决定。
目录app
对于新应用程序,我们建议使用App Router。该路由器允许您使用 React 的最新功能,并且是基于社区反馈的Pages Router的演变。
创建一个app/
文件夹,然后添加一个layout.tsx
文件page.tsx
。当用户访问应用程序的根目录 ( /
) 时,将呈现这些内容。
使用所需的和标签在内部创建根布局:app/layout.tsx<html><body>
//app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
最后,创建一个包含一些初始内容的主页app/page.tsx
:
//app/page.tsx
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
值得注意的是:如果您忘记创建
layout.tsx
,Next.js 将在运行开发服务器时自动创建此文件next dev
。
pages
目录(可选)
如果您更喜欢使用页面路由器而不是应用程序路由器,您可以pages/
在项目的根目录下创建一个目录。
然后,在文件夹index.tsx
中添加一个文件pages
。这将是您的主页 ( /
):
//pages/index.tsx
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
接下来,在里面添加一个_app.tsx
文件pages/
来定义全局布局。
//pages/_app.tsx
import type { AppProps } from 'next/app'
export default function App({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />
}
最后,在里面添加一个_document.tsx
文件pages/
来控制服务器的初始响应。
//pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
值得注意的是:虽然您可以在同一项目中使用两个路由器,但 in 的路由
app
将优先于pages
。我们建议在您的新项目中仅使用一台路由器以避免混淆。
public
文件夹(可选)
创建一个public
文件夹来存储静态资源,例如图像、字体等。然后,public
您的代码可以从基本 URL ( ) 开始引用目录中的文件/
。
运行开发服务器
运行
npm run dev
以启动开发服务器。访问
http://localhost:3000
以查看您的申请。编辑
app/page.tsx
(或pages/index.tsx
)文件并保存以在浏览器中查看更新的结果。
项目结构
此页面概述了 Next.js 应用程序的项目结构。它涵盖了顶级文件和文件夹、配置文件以及 和 目录中的路由app
约定pages
。
顶级文件夹
顶级文件夹用于组织应用程序的代码和静态资产。
| App 路由 |
| 页面路由 |
| 静态资源目录 |
| 可选的源代码文件夹 |
顶级文件
顶级文件用于配置应用程序、管理依赖项、运行中间件、集成监视工具以及定义环境变量。
| Next.js 的配置文件 |
| 项目依赖和脚本 |
| OpenTelemetry 和 Instrumentation 文件 |
| Next.js 请求中间件 |
| 环境变量 |
| 本地环境变量 |
| 生产环境变量 |
| 开发环境变量 |
| ESLint 的配置文件 |
| 要忽略的 Git 文件和文件夹 |
| Next.js 的 TypeScript 声明文件 |
| TypeScript 的配置文件 |
| JavaScript 的配置文件 |
app路由
路由文件
|
| 布局 |
|
| 页 |
|
| 加载用户界面 |
|
| 未找到用户界面 |
|
| 错误用户界面 |
|
| 全局错误用户界面 |
|
| API端点 |
|
| 重新渲染布局 |
|
| 并行路由后备页面 |
嵌套路由
| 航线段 |
| 嵌套路由段 |
动态路由
| 动态路段 |
| 包罗万象的路线段 |
| 可选的包罗万象的路线段 |
路由组和私有目录
| 对路由进行分组而不影响路由 |
| 选择文件夹和所有子段不参与路由 |
并行和拦截路由
| 命名槽 |
| 拦截同级 |
| 拦截上面一层 |
| 拦截上面两层 |
| 从根拦截 |
元数据文件约定
应用程序图标
favicon
.ico
网站图标文件
icon
.ico
.jpg
.jpeg
.png
.svg
应用程序图标文件
icon
.js
.ts
.tsx
生成的应用程序图标
apple-icon
.jpg
.jpeg
,.png
苹果应用程序图标文件
apple-icon
.js
.ts
.tsx
生成的苹果应用程序图标
图片和Twitter图片
opengraph-image
.jpg
.jpeg
.png
.gif
打开图形图像文件
opengraph-image
.js
.ts
.tsx
生成的 Open Graph 图像
twitter-image
.jpg
.jpeg
.png
.gif
Twitter图像文件
twitter-image
.js
.ts
.tsx
生成的 Twitter 图片
SEO
sitemap
.xml
站点地图文件
sitemap
.js
.ts
生成的站点地图
robots
.txt
机器人文件
robots
.js
.ts
生成的机器人文件
pages
的路由约定
特殊文件
|
| 定制应用程序 |
|
| 定制文件 |
|
| 自定义错误页面 |
|
| 404错误页面 |
|
| 500 错误页面 |
路由
文件夹约定 | ||
|
| 主页 |
|
| 嵌套页面 |
文件约定 | ||
|
| 主页 |
|
| 嵌套页面 |
动态路由
文件夹约定 | ||
|
| 动态路段 |
|
| 包罗万象的路线段 |
|
| 可选的包罗万象的路线段 |
文件约定 | ||
|
| 动态路段 |
|
| 包罗万象的路线段 |
|
| 可选的包罗万象的路线段 |
构建您的应用程序
Next.js 提供了创建灵活的全栈 Web 应用程序的构建块。构建您的应用程序中的指南解释了如何使用这些功能以及如何自定义应用程序的行为。
这些部分和页面按从基础到高级的顺序组织,因此您可以在构建 Next.js 应用程序时逐步遵循它们。但是,您可以按任何顺序阅读它们或跳至适用于您的用例的页面。
路由
每个应用程序的骨架都是路由。本页面将向您介绍Web 路由的基本概念以及如何在 Next.js 中处理路由。
术语
首先,您将看到整个文档中使用了这些术语。这是一个快速参考:
Tree:可视化层次结构的约定。例如,具有父组件和子组件的组件树、文件夹结构等。
SubTree:树的一部分,从新的根(第一个)开始,到叶子(最后一个)结束。
Root:树或子树中的第一个节点,例如根布局。
Leaf:子树中没有子节点的节点,例如 URL 路径中的最后一段。
URL Segment:由斜杠分隔的 URL 路径的一部分。
URL Path:域名后面的 URL 部分(由段组成)。
app
路由
在版本 13 中,Next.js 引入了一个基于React Server Components构建的新App Router,它支持共享布局、嵌套路由、加载状态、错误处理等。
App Router 在名为 的新目录中工作app
。该app
目录与目录一起工作pages
,以允许增量采用。这允许您将应用程序的某些路由选择为新行为,同时将其他路由保留在pages
先前行为的目录中。如果您的应用程序使用该pages
目录,另请参阅Pages Router文档。
值得注意的是:App Router 的优先级高于 Pages Router。跨目录的路由不应解析为相同的 URL 路径,并且会导致构建时错误以防止冲突。
默认情况下,里面的组件app
是React Server Components。这是一种性能优化,可以让您轻松采用它们,并且您还可以使用Client Components。