技术文档

Appearance

前言 ​

欢迎学习 Next.js.本知识点是个人用来学习 Next.js 的笔记，如有错误，请指正。

本知识点 我借鉴了 我借鉴了Next.js 官方文档 和掘金手册的 Next.js 开发指南 - 冴羽

在此特别感谢 Next 官方和冴羽对本人的帮助

Next.js ​

欢迎学习 Next.js！在学习具体的知识点之前，我们先来创建一个 Next.js 项目。创建了可运行的项目，才能在学习的时候边调试边理解，从而达到事半功倍的效果。

幸运的是，Next.js 提供了开箱即用的 create-next-app 脚手架，内置支持 TypeScript、ESLint 等功能，零配置即可实现自动编译和打包。

本篇我们会讲解创建项目的两种方式：自动创建项目和手动创建项目，以及开发项目时常用的脚本命令。同时我们会对脚本背后的 next 命令进行详解，帮助大家了解每个命令实现的功能和可选参数。

知识点 ​

  • 本章知识点

注意

  1. 自动创建项目

  2. 手动创建项目

  3. 脚本命令

自动创建项目 ​

环境要求 ​

此本小册基于的是目前最新版本的 v15 版本，需要 Node.js 18.17 及以后版本，支持 macOS、Windows、Linux 系统。

创建项目 ​

最快捷的创建 Next.js 项目的方式是使用 create-next-app 脚手架，你只需要运行：

bash

npx create-next-app@latest
  • 创建完以后会有下面的步骤
bash
// 是否需要TS  我选择的是No
Would you like to use TypeScript? » No / Yes

// 代码检查工具  我选择的是Yes
Which linter would you like to use
    ESLint - More comprehensive lint rules
    Biome
    None

//  是否使用css 原子化, 我选择的是Yes
Would you like to use Tailwind CSS? » No / Yes

// 是否用src包裹 No

Would you like your code inside a `src/` directory? » No / Yes

// 是否用Approuter Yes

Would you like to use App Router? (recommended) » No / Yes

// Turbopack 打包工具 No

Would you like to use Turbopack? (recommended) » No / Yes

// 是否使用别名 Yes

Would you like to customize the import alias (`@/*` by default)? » No / Yes

// 别名配置
What import alias would you like configured? » @/*
  • 创建完以后会有如下目录
  • 如果你不使用 npx，也支持使用 yarn、pnpm、bunx：
bash
yarn create next-app

或者

bash

pnpm create next-app

或者

bash

bunx create-next-app

运行项目 ​

查看项目根目录 package.json 文件代码:

ts

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },

我们可以看到脚本命令有 dev、build、start、lint，分别对应开发、构建、运行、代码检查。

注意

  1. 开发的时候使用npm run dev

  2. 部署的时候先使用npm run build 再使用 npm run start 运行生产项目

  3. 运行 npm run lint 则会执行 ESLint 语法检查。

  • 现在让我们执行npm run dev 运行项目

命令行会提示运行在 3000 端口，我们在浏览器打开页面 http://localhost:3000/，看到如下内容即表示项目成功运行：

注意

学习的时候为了避免浏览器插件带来的影响，建议在无痕模式下测试。

示例代码 ​

Next.js 提供了丰富的示例代码，比如 with-redux、api-routes-cors、with-electron、with-jest、with-markdown、with-material-ui、with-mobx，从这些名字中也可以看出，这些示例代码演示了 Next.js 的各种使用场景，比如 with-redux 就演示了 Next.js 如何与 redux 搭配使用。

你可以访问https://github.com/vercel/next.js/tree/canary/examples 查看有哪些示例代码,如果你想直接使用某个示例代码就比如with-redux无需手动 clone 代码,在创建的时候使用--example参数即可直接创建

bash

npx create-next-app --example with-redux your-app-name

注意

用示例代码的时候，并不会像执行 npx create-next-app 时提示是否使用 TypeScript、ESLint 等，而是会直接进入项目创建和依赖安装阶段。

手动创建项目 ​

大部分时候我们并不需要手动创建 Next.js 项目，但了解这个过程有助于我们认识到一个最基础的 Next.js 项目依赖哪些东西。

创建文件夹并且安装依赖 ​

现在，创建一个文件夹，假设名为 next-app-manual，cd 进入该目录，安装依赖：

bash

npm install next@latest react@latest react-dom@latest

npm 会自动创建 package.json 并安装依赖项。

添加 scripts ​

  • 找到package.json 文件，添加 scripts 字段：
ts
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

创建目录 ​

在 next-app-manual 下新建 app 文件夹，app 下新建 layout.js 和 page.js 文件，代码如下：

js
// app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

-app/page.js 文件代码如下：

js
// app/page.js
export default function Page() {
  return <h1>Hello, Next.js!</h1>;
}

运行项目 ​

现在运行 npm run dev，正常渲染则表示运行成功：

Next.jsCLI 命令详解 ​

查看所有的命令 ​

  • npx next -h

打包命令 ​

  • npx next build

构建输出:

这里要解释一下 Size 和 First Load JS 的含义。正常我们开发的 Next.js 项目，其页面表现类似于单页应用 即路由跳转（我们称之为“导航”）的时候，页面不会刷新，而会加载目标路由所需的资源然后展示，所以：

注意

  1. 加载目标路由一共所需的 JS 大小 = 每个路由都需要依赖的 JS 大小 + 目标路由单独依赖的 JS 大小

  2. 加载目标路由一共所需的 JS 大小就是 First Load JS

  3. 目标路由单独依赖的 JS 大小就是 Size

  4. 每个路由都需要依赖的 JS 大小就是图中单独列出来的 First load JS shared by all

也就是说

First Load JS 就是最后加载这个页面所需的大小

  • npx run build --debug

开启后，将输出额外的构建输出信息如 rewrites、redirects、headers。

这样开启后你可以看到相比之前的构建输出信息，多了 rewrites、redirects 等信息。关于 rewrites、redirects 的具体用法

运行命令 ​

  • npx next dev

开发模式下，使用 next dev 运行程序，会自动具有热加载、错误报告等功能。默认情况下，程序将在 http://localhost:3000 开启。如果你想更改端口号：

ts
npx next dev -p 4000

或者在package.json下面写start:port4000命令

bash
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "start:port4000": "next start --port 4000"
  },
  • 如果你想更改主机名（hostname）：（以便其他主机访问）
bash
npx next dev -H 192.168.1.2

部署命令 ​

  • npx next start

生产模式下，使用 next start 运行程序。不过要先执行 next build 构建出生产代码。运行的时候，跟开发模式相同，程序默认开启在 http://localhost:3000。如果你想更改端口号：

bash
npx next start -p 4000

语法检查命令 ​

  • npx next lint --dir utils

执行 next lint 会为 pages/、app/、components/、lib/、src/目录下的所有文件执行 ESLint 语法检查。

如果你没有安装 ESLint，该命令会提供一个安装指导。如果你想要指定检查的目录：

ts

npx next lint --dir utils

总结 ​

这一节我们讲解了自动创建项目和手动创建项目两种创建项目的方式，如果是全新的项目，推荐使用自动创建方式。如果是项目中引入 Next.js，可以参考手动创建项目的方式。

Next.js 项目常用的脚本有三个:

    1. npm run dev 用于开发时使用
    1. npm run build 用于构建生产版本
    1. npm run start 用于运行生产版本

靡不有初，鲜克有终。恭喜你迈出第一步！接下来我们将进入路由篇

网站备案号:津ICP备15001525号-2