NEXT.js 14 中文文档

React

2024年03月08日 10:30:141456

本文档由本人在next官网,通过文档学习的形式,翻译而来。

官网链接:https://nextjs.org/docs

本文档持续跟新中

入门

  1. 什么是Next.js

Next.js 是一个用于构建全栈 Web 应用程序的 React 框架。您可以使用 React Components 来构建用户界面,并使用 Next.js 来实现附加功能和优化。

在底层,Next.js 还抽象并自动配置 React 所需的工具,例如捆绑、编译等。这使您可以专注于构建应用程序,而不是花时间进行配置。

无论您是个人开发人员还是大型团队的一员,Next.js 都可以帮助您构建交互式、动态且快速的 React 应用程序。

  1. 主要特点

Next.js 的一些主要功能包括:

特征

描述

路由

基于文件系统的路由器构建在服务器组件之上,支持布局、嵌套路由、加载状态、错误处理等。

渲染

使用客户端和服务器组件进行客户端和服务器端渲染。使用 Next.js 在服务器上进一步优化静态和动态渲染。在 Edge 和 Node.js 运行时上进行流式传输。

数据获取

通过服务器组件中的 async/await 简化数据获取,以及fetch用于请求记忆、数据缓存和重新验证的扩展 API。

造型

支持您喜欢的样式方法,包括 CSS 模块、Tailwind CSS 和 CSS-in-JS

优化

图像、字体和脚本优化,以改善应用程序的核心网络生命和用户体验。

TypeScript

改进了对 TypeScript 的支持,提供更好的类型检查和更高效的编译,以及自定义 TypeScript 插件和类型检查器。

  1. 应用程序路由于页面路由

Next.js 有两个不同的路由器:App Router 和 Pages Router。App Router 是一个较新的路由器,允许您使用 React 的最新功能,例如服务器组件和流媒体。Pages Router 是原始的 Next.js 路由器,它允许您构建服务器渲染的 React 应用程序,并继续支持旧版 Next.js 应用程序。

安装

系统要求

  • Node.js 18.17或更新版本

  • 支持 macOS、Windows(包括 WSL)和 Linux。

  1. 自动安装

我们建议使用 启动一个新的 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将创建一个包含您的项目名称的文件夹并安装所需的依赖项。

  1. 手动安装

要手动创建新的 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 配置。

  1. 创建目录

Next.js 使用文件系统路由,这意味着应用程序中的路由由您构建文件的方式决定。

目录app

对于新应用程序,我们建议使用App Router。该路由器允许您使用 React 的最新功能,并且是基于社区反馈的Pages Router的演变。

创建一个app/文件夹,然后添加一个layout.tsx文件page.tsx。当用户访问应用程序的根目录 ( /) 时,将呈现这些内容。

//cdn.shiniest.cn/static/202403/app-getting-started.avif

使用所需的和标签在内部创建根布局: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 ( ) 开始引用目录中的文件/

  1. 运行开发服务器

  • 运行npm run dev以启动开发服务器。

  • 访问http://localhost:3000以查看您的申请。

  • 编辑app/page.tsx(或pages/index.tsx)文件并保存以在浏览器中查看更新的结果。

项目结构

此页面概述了 Next.js 应用程序的项目结构。它涵盖了顶级文件和文件夹、配置文件以及 和 目录中的路由app约定pages

  1. 顶级文件夹

顶级文件夹用于组织应用程序的代码和静态资产。

//cdn.shiniest.cn/static/202403/top-level-folders.avif

app

App 路由

pages

页面路由

public

静态资源目录

src

可选的源代码文件夹

  1. 顶级文件

顶级文件用于配置应用程序、管理依赖项、运行中间件、集成监视工具以及定义环境变量。

next.config.js

Next.js 的配置文件

package.json

项目依赖和脚本

instrumentation.ts

OpenTelemetry 和 Instrumentation 文件

middleware.ts

Next.js 请求中间件

.env

环境变量

.env.local

本地环境变量

.env.production

生产环境变量

.env.development

开发环境变量

.eslintrc.json

ESLint 的配置文件

.gitignore

要忽略的 Git 文件和文件夹

next-env.d.ts

Next.js 的 TypeScript 声明文件

tsconfig.json

TypeScript 的配置文件

jsconfig.json

JavaScript 的配置文件

  1. app路由

  • 路由文件

layout

.js .jsx .tsx

布局

page

.js .jsx .tsx

loading

.js .jsx .tsx

加载用户界面

not-found

.js .jsx .tsx

未找到用户界面

error

.js .jsx .tsx

错误用户界面

global-error

.js .jsx .tsx

全局错误用户界面

route

.js .ts

API端点

template

.js .jsx .tsx

重新渲染布局

default

.js .jsx .tsx

并行路由后备页面

  • 嵌套路由

folder

航线段

folder/folder

嵌套路由段

  • 动态路由

[folder]

动态路段

[...folder]

包罗万象的路线段

[[...folder]]

可选的包罗万象的路线段

  • 路由组和私有目录

(folder)

对路由进行分组而不影响路由

_folder

选择文件夹和所有子段不参与路由

  • 并行和拦截路由

@folder

命名槽

(.)folder

拦截同级

(..)folder

拦截上面一层

(..)(..)folder

拦截上面两层

(...)folder

从根拦截

  • 元数据文件约定

    • 应用程序图标

      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

      生成的机器人文件

  1. pages的路由约定

  • 特殊文件

_app

.js .jsx .tsx

定制应用程序

_document

.js .jsx .tsx

定制文件

_error

.js .jsx .tsx

自定义错误页面

404

.js .jsx .tsx

404错误页面

500

.js .jsx .tsx

500 错误页面

  • 路由

文件夹约定

index

.js .jsx .tsx

主页

folder/index

.js .jsx .tsx

嵌套页面

文件约定

index

.js .jsx .tsx

主页

file

.js .jsx .tsx

嵌套页面

  • 动态路由

文件夹约定

[folder]/index

.js .jsx .tsx

动态路段

[...folder]/index

.js .jsx .tsx

包罗万象的路线段

[[...folder]]/index

.js .jsx .tsx

可选的包罗万象的路线段

文件约定

[file]

.js .jsx .tsx

动态路段

[...file]

.js .jsx .tsx

包罗万象的路线段

[[...file]]

.js .jsx .tsx

可选的包罗万象的路线段

构建您的应用程序

Next.js 提供了创建灵活的全栈 Web 应用程序的构建块。构建您的应用程序中的指南解释了如何使用这些功能以及如何自定义应用程序的行为。

这些部分和页面按从基础到高级的顺序组织,因此您可以在构建 Next.js 应用程序时逐步遵循它们。但是,您可以按任何顺序阅读它们或跳至适用于您的用例的页面。

路由

每个应用程序的骨架都是路由。本页面将向您介绍Web 路由的基本概念以及如何在 Next.js 中处理路由。

  1. 术语

首先,您将看到整个文档中使用了这些术语。这是一个快速参考:

//cdn.shiniest.cn/static/202403/terminology-component-tree.avif
  • Tree:可视化层次结构的约定。例如,具有父组件和子组件的组件树、文件夹结构等。

  • SubTree:树的一部分,从新的根(第一个)开始,到叶子(最后一个)结束。

  • Root:树或子树中的第一个节点,例如根布局。

  • Leaf:子树中没有子节点的节点,例如 URL 路径中的最后一段。

//cdn.shiniest.cn/static/202403/terminology-url-anatomy.avif
  • URL Segment:由斜杠分隔的 URL 路径的一部分。

  • URL Path:域名后面的 URL 部分(由段组成)。

  1. 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。

定义路由

页面和布局

链接和导航

加载UI和流式传输

错误处理

重定向

路由组

项目组织

动态路由

平行路由

拦截路由

路由处理程序

中间件

国际化

数据获取

获取、缓存和重新验证

服务器操作和(数据)变化

数据获取模式和最佳实践

渲染

服务端组件

客户端组件

组合模式

Edge和Node.js运行时

缓存

样式

CSS模块

Tailwind CSS

JS中的CSS

Sass

优化

图片

视频

字体

元数据

脚本

捆绑分析仪

延迟加载

分析

检测

OpenTelemetry(开放式测试框架)

静态资源

第三方库

配置

TypeScript

EsLint

环境变量

绝对导入和模块路径别名

MDX

src目录

草稿模式

内容安全政策

测试

Vitest

Jest

Playwright

Cypress

验证

部署

生产清单

静态导出

升级

代码模组

App路由迁移

版本14

从Vite迁移

从Create React App迁移

API参考

组件

Font

<Image>

<Link>

<Script>

文件

default.js

error.js

instrumentation.js

layout.js

loading.js

middleware.js

not-found.js

page.js

route.js

路由段配置

template.js

元数据文件

favicon, icon, apple-icon
mainfist.json
opengraph-image和twitter-image
robots.txt
sitemap.xml

功能

cookies

草稿模式(draftMode)

fetch

生成图像元数据 - generateImageMetadata

生成元数据 - generateMetadata

生成站点地图 - generateSitemaps

生成静态参数 - generateStaticParams

生成Viewport - generateViewport

标头 - headers

图像响应 - ImageResponse

请求 - NextRequest

响应 - NextResponse

未找到 - notFound

永久重定向 - permanentRedirect

重定向 - redirect

重新验证路径 - revalidatePath

重新验证标签 - revalidateTag

不稳定的缓存 - unstable_cache

不稳定_无存储 - unstable_noStore

参数 - useParams

路径名 - usePathname

Web状态 - useReportWebVitals

路由 - useRouter

搜索参数 - useSearchParams

选定布局 - useSelectedLayoutSegment

多重选定布局 - useSelectedLayoutSegments

用户媒介 - userAgent

next.config.js选项

应用程序目录 - appDir

资源前缀 - assetPrefix

基本路径 - basePath

压缩 - compress

跨域 - crosOrigin

开发指标 - devIndicators

dist目录 - distDir

环境 - env

eslint

导出路径映射 - exportPathMap

生成构建ID - generateBuildId

生成Etags - generateEtags

标头 - headers

http代理选项 - httpAgentOptions

图片 - images

缓存处理程序 - cacheHandler

仪器钩子 - instrumentationHook

日志 - logging

mdxRs

请求条目 - onDemandEntries

优化包导入 - optimizePackageImports

输出 - output

页面扩展 - pageExtensions

部分预渲染(实验性) - Partial Prerendering (experimental)

由标题提供支持 - poweredByHeader

生产浏览器源图 - productionBrowserSourceMaps

反应严格模式 - reactStrictMode

重定向 - redirects

重写 - rewrites

服务器动作 - serverActions

服务器组件外部包 - serverComponentsExternalPackages

尾部斜杠 - trailingSlash

转译包 - transpilePackages

涡轮 - turbo

类型路由 - typedRoutes

typescript

url导入 - urlImports

网络包 - webpack

Web状态归因 - webVitalsAttribution

create-next-app

Edge运行时

Next.js脚手架

结构

无障碍

快速刷新

Next.js编译器

支持的浏览器

增量捆绑器 - Turbopack

社区

贡献指南

赞 3
收藏
分享

本作品系 原创,作者:你不熟悉的x先生

原文链接:https://shiniest.cn/blog/article/164

文本版权:文本版权归作者所有

转载需著名并注明出处(禁止商业使用)

评论和回复

0/500
    没有更多啦~
    怎么一条数据都没有呢?
简介
Next.js 是一个用于构建全栈 Web 应用程序的 React 框架。您可以使用 React Components 来构建用户界面,并使用 Next.js 来实现附加功能和优化。在底层,Next.js 还抽象并自动配置 React 所需的工具,例如捆绑、编译等。这使您可以专注于构建应用程序,而不是花时间进行配置。无论您是个人开发人员还是大型团队的一员,Next.js 都可以帮助您构建交互式、动态且快速的 React 应用程序。
目录

D&D By x先生 With