Next.js手把手系列：01、初始篇 | Next.js CLI #88

MagicalBridge · 2024-07-14T06:56:01Z

前言

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

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

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

1. 自动创建项目

1.1. 环境要求

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

1.2. 创建项目

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

npx create-next-app@latest

接下来会有一系列的操作提示，比如设置项目名称、是否使用 TypeScript、是否开启 ESLint、是否使用 Tailwind CSS 等，根据自己的实际情况进行选择即可。如果刚开始你不知道如何选择，遵循默认选择即可，这些选择的作用我们会随着小册的学习逐渐了解。

注：为了减少学习成本，此本小册的示例代码就不使用 TypeScript 了。（想学习 TypeScript 的同学可以看官方文档）

完成选择之后，create-next-app 会自动创建项目文件并安装依赖，创建安装完的项目目录和文件如下：

如果你不使用 npx，也支持使用 yarn、pnpm、bunx：

yarn create next-app

pnpm create next-app

bunx create-next-app

1.3. 运行项目

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

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

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

开发的时候使用 npm run dev。部署的时候先使用 npm run build 构建生产代码，再执行 npm run start 运行生产项目。运行 npm run lint 则会执行 ESLint 语法检查。

现在我们执行 npm run dev 运行项目吧！

命令行会提示运行在 3000 端口，我们在浏览器打开页面 http://localhost:3000/

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

1.4. 示例代码

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 搭配使用。

你可以访问 github.com/vercel/next… 查看有哪些示例代码。如果你想直接使用某个示例代码，就比如 with-redux，无须手动 clone 代码，在创建项目的时候使用 --example 参数即可直接创建：

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

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

2. 手动创建项目

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

2.1. 创建文件夹并安装依赖

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

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

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

2.2. 添加 scripts

打开 package.json，添加以下内容：

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

2.3. 创建目录

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

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

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

2.4. 运行项目

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

3. Next.js CLI

通过 package.json 中的代码我们知道：当我们运行 npm run dev 的时候，其实执行的是 next dev。next 命令就是来自于 Next.js CLI。Next.js CLI 可以帮助你启动、构建和导出项目。

完整的 CLI 命令，你可以执行 npx next -h 查看（-h 是 --help 的简写）。

注：因为我们是使用 npx创建的项目，这种方式下避免了全局安装 create-next-app，所以我们本地全局并无 next 命令。如果你要执行 next 命令，可以在 next前加一个 npx，就比如这次用到的 npx next -h

3.1. next build

执行 next build 将会创建项目的生产优化版本：

npx next build

构建输出如下：

从上图可以看出，构建时会输出每条路由的信息，比如 Size 和 First Load JS。注意这些值指的都是 gzip 压缩后的大小。

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

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

其中：

加载目标路由一共所需的 JS 大小就是 First Load JS
目标路由单独依赖的 JS 大小就是 Size
每个路由都需要依赖的 JS 大小就是图中单独列出来的 First load JS shared by all

也就是说：

First Load JS = Size + First load JS shared by all

以上图中的 / 路由地址为例，89 kB（First Load JS）= 5.16 kB（Size） + 83.9 kB（First load JS shared by all）

使用官方文档中的介绍就是：

Size：导航到该路由时下载的资源大小，每个路由的大小只包括它自己的依赖项
First Load JS：加载该页面时下载的资源大小
First load JS shared by all：所有路由共享的 JS 大小会被单独列出来

3.2. next dev

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

npx next dev -p 4000

如果你想更改主机名（hostname）：（以便其他主机访问）

npx next dev -H 192.168.1.2

3.3. next start

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

bash

复制代码npx next start -p 4000

3.4. next lint

执行 next lint会为 pages/、app/、components/、lib/、src/目录下的所有文件执行 ESLint 语法检查。如果你没有安装 ESLint，该命令会提供一个安装指导。如果你想要指定检查的目录：

bash

复制代码npx next lint --dir utils

3.5. next info

next info会打印当前系统相关的信息，可用于报告 Next.js 程序的 bug。在项目的根目录中执行：

npx next info

打印信息类似于：

Operating System:
  Platform: linux
  Arch: x64
  Version: #22-Ubuntu SMP Fri Nov 5 13:21:36 UTC 2021
Binaries:
  Node: 16.13.0
  npm: 8.1.0
  Yarn: 1.22.17
  pnpm: 6.24.2
Relevant packages:
  next: 12.0.8
  react: 17.0.2
  react-dom: 17.0.2

这些信息可以贴到 GitHub Issues 中方便 Next.js 官方人员排查问题。

小结

恭喜你，完成本篇内容的学习！

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

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

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

从 package.json中，我们得知这些脚本背后用的其实是 Next.js CLI 的 next 命令，然后我们对常用的 next 命令和相关参数进行了介绍。在必要的时候，可以使用这些命令和参数自定义 npm 脚本。

参考链接

The text was updated successfully, but these errors were encountered:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Next.js手把手系列：01、初始篇 | Next.js CLI #88

Next.js手把手系列：01、初始篇 | Next.js CLI #88

MagicalBridge commented Jul 14, 2024

Next.js手把手系列：01、初始篇 | Next.js CLI #88

Next.js手把手系列：01、初始篇 | Next.js CLI #88

Comments

MagicalBridge commented Jul 14, 2024

前言

1. 自动创建项目

1.1. 环境要求

1.2. 创建项目

1.3. 运行项目

1.4. 示例代码

2. 手动创建项目

2.1. 创建文件夹并安装依赖

2.2. 添加 scripts

2.3. 创建目录

2.4. 运行项目

3. Next.js CLI

3.1. next build

3.2. next dev

3.3. next start

3.4. next lint

3.5. next info

小结

参考链接