Next.js 开发指南初始篇 | Next.js CLI - Powered by Discuz! Archiver

族家發表於 2024-1-6 11:38:00

Next.js 开发指南初始篇 | Next.js CLI

<div class="desc text-line-2" title="基础篇、实战篇、源码篇、面试篇四大篇章带你系统掌握 Next.js！" data-v-7f58db46="" data-v-5762947c="">基础篇、实战篇、源码篇、面试篇四大篇章带你系统掌握 Next.js！</div>
<div class="desc text-line-2" title="基础篇、实战篇、源码篇、面试篇四大篇章带你系统掌握 Next.js！" data-v-7f58db46="" data-v-5762947c=""> </div>
<div class="desc text-line-2" title="基础篇、实战篇、源码篇、面试篇四大篇章带你系统掌握 Next.js！" data-v-7f58db46="" data-v-5762947c="">
<h2 data-id="heading-0">前言</h2>
欢迎学习 Next.js！在学习具体的知识点之前，我们先来创建一个 Next.js 项目。创建了可运行的项目，才能在学习的时候边调试边理解，从而达到事半功倍的效果。
幸运的是，Next.js 提供了开箱即用的 <code>create-next-app</code>脚手架，内置支持 TypeScript、ESLint 等功能，零配置即可实现自动编译和打包。
本篇我们会讲解创建项目的两种方式：自动创建项目和手动创建项目，以及开发项目时常用的脚本命令。同时我们会对脚本背后的 <code>next</code> 命令进行详解，帮助大家了解每个命令实现的功能以及可选参数。
<h2 data-id="heading-1">1. 自动创建项目</h2>
<h3 data-id="heading-2">1.1. 环境要求</h3>
此本小册基于的是目前最新版本的 v14 版本，需要 Node.js 18.17 及以后版本，支持 macOS、Windows、Linux 系统。
<h3 data-id="heading-3">1.2. 创建项目</h3>
最快捷的创建 Next.js 项目的方式是使用 <code>create-next-app</code>脚手架，你只需要执行：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npx create-next-app@latest
</code></pre>
接下来会有一系列的操作提示，比如设置项目名称、是否使用 TypeScript、是否开启 ESLint、是否使用 Tailwind CSS 等，根据自己的实际情况进行选择即可。如果刚开始你不知道如何选择，遵循默认选择即可，这些选择的作用我们会随着小册的学习逐渐了解。
注：为了减少展示的代码量，此本小册的示例代码并未使用 TypeScript。（想学习 TypeScript 的同学可以看我整理的最新的 TypeScript 官方文档）
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ec2fc0641cf1438cafdf1197b2f58771~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1098&h=320&s=611781&e=png&b=03090e" alt="image.png" class="medium-zoom-image">
完成选择之后，<code>create-next-app</code> 会自动创建项目文件并安装依赖，创建安装完的项目目录和文件如下：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/76e218812d164d8a98212ac18342c56c~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1228&h=592&s=117964&e=png&b=1d1e20" alt="image.png" class="medium-zoom-image">
如果你不使用 <code>npx</code>，也支持使用 <code>yarn</code>、<code>pnpm</code>、<code>bunx</code>：
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">yarn create next-app
</code></pre>
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">pnpm create next-app
</code></pre>
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">bunx create-next-app
</code></pre>
<h3 data-id="heading-4">1.3. 运行项目</h3>
查看项目根目录 <code>package.json</code> 文件的代码：
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">// package.json
"scripts": {
 "dev": "next dev",
 "build": "next build",
 "start": "next start",
 "lint": "next lint"
},
</code></pre>
我们可以看到执行命令有 <code>dev</code>、<code>build</code>、<code>start</code>、<code>lint</code>，分别对应开发、构建、运行、代码检查。
开发的时候使用 <code>npm run dev</code>。部署的时候先使用 <code>npm run build</code>构建生产代码，再执行 <code>npm run start</code>运行生产项目。运行 <code>npm run lint</code>则会执行 ESLint 语法检查。
现在我们执行 <code>npm run dev</code> 运行项目吧！
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/02fe813e102e4adf98f1c3e30b3d7e82~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=700&h=410&s=379156&e=png&b=02060a" alt="image.png" class="medium-zoom-image">
命令行会提示运行在 <code>3000</code> 端口，我们在浏览器打开页面 http://localhost:3000/，看到如下内容即表示项目成功运行：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9e8626c484a0463ab08325e411647e56~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=3038&h=2558&s=516125&e=png&b=000000" alt="image.png" class="medium-zoom-image">
注：学习的时候为了避免浏览器插件带来的影响，建议在无痕模式下测试。
<h3 data-id="heading-5">1.4. 示例代码</h3>
Next.js 提供了丰富的示例代码，比如 <code>with-redux</code>、<code>api-routes-cors</code>、<code>with-electron</code>、<code>with-jest</code>、<code>with-markdown</code>、<code>with-material-ui</code>、<code>with-mobx</code>，从这些名字中也可以看出，这些示例代码演示了 Next.js 的各种使用场景，比如 <code>with-redux</code>就演示了 Next.js 如何与 redux 搭配使用。
你可以访问 github.com/vercel/next… 来查看有哪些示例代码。如果你想直接使用某个示例代码，就比如 <code>with-redux</code>，无须手动 clone 代码，在创建项目的时候使用 <code>--example</code> 参数即可直接创建：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npx create-next-app --example with-redux your-app-name
</code></pre>
注：使用示例代码的时候，并不会像执行 <code>npx create-next-app</code>时提示是否使用 TypeScript、ESLint 等，而是会直接进入项目创建和依赖安装。
<h2 data-id="heading-6">2. 手动创建项目</h2>
大部分时候我们并不需要手动创建 Next.js 项目，但了解这个过程有助于我们认识到一个最基础的 Next.js 项目依赖哪些东西。
<h3 data-id="heading-7">2.1. 创建文件夹并安装依赖</h3>
现在，创建一个文件夹，假设名为 <code>next-app-manual</code>，<code>cd</code> 进入该目录，安装依赖：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npm install next@latest react@latest react-dom@latest
</code></pre>
npm 会自动创建 <code>package.json</code> 并安装依赖项。
<h3 data-id="heading-8">2.2. 添加 scripts</h3>
打开 <code>package.json</code>，添加以下内容：
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">{
"scripts": {
 "dev": "next dev",
 "build": "next build",
 "start": "next start",
 "lint": "next lint"
}
}
</code></pre>
<h3 data-id="heading-9">2.3. 创建目录</h3>
在 <code>next-app-manual</code>下创建一个 <code>layout.js</code> 和 <code>page.js</code>文件：
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">// app/layout.js
export default function RootLayout({ children }) {
return (
 <html lang="en">
 <body>{children}</body>
 </html>
)
}
</code></pre>
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">// app/page.js
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
</code></pre>
<h3 data-id="heading-10">2.4. 运行项目</h3>
现在运行 <code>npm run dev</code>，正常渲染则表示运行成功：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f15914cd6c544635ab145cc001d06345~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1564&h=268&s=35009&e=png&b=ffffff" alt="image.png" class="medium-zoom-image">
<h2 data-id="heading-11">3. Next.js CLI</h2>
通过 <code>package.json</code> 中的代码我们知道：当我们运行 <code>npm run dev</code> 的时候，其实执行的是 <code>next dev</code>。<code>next</code> 命令就是来自于 Next.js CLI。Next.js CLI 可以帮助你启动、构建和导出项目。
完整的 CLI 命令，你可以执行 <code>npx next -h</code> 查看（<code>-h</code> 是 <code>--help</code> 的简写）。
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5cf4b85fa2194c9ea26bb20e9d29008c~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1328&h=626&s=1246629&e=png&b=03080d" alt="image.png" class="medium-zoom-image">
从上图可以看到，<code>next</code> 可以执行的命令有多个，我们介绍下最常用的一些。
注：因为我们是使用 <code>npx</code>创建的项目，这种方式下避免了全局安装 <code>create-next-app</code>，所以我们本地全局并无 <code>next</code> 命令。如果你要执行 <code>next</code> 命令，可以在 <code>next</code>前加一个 <code>npx</code>，就比如这次用到的 <code>npx next -h</code>
<h3 data-id="heading-12">3.1. next build</h3>
执行 <code>next build</code> 将会创建项目的生产优化版本：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npx next build
</code></pre>
构建输出如下：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c4f2e351301d45699599287c0c86f779~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1016&h=760&s=1040533&e=png&b=02070b" alt="image.png" class="medium-zoom-image">
从上图可以看出，构建时会输出每条路由的信息，比如 Size 和 First Load JS。注意这些值指的都是 gzip 压缩后的大小。其中 First Load JS 会用绿色、黄色、红色表示，绿色表示高性能，黄色或红色表示需要优化。
这里要解释一下 Size 和 First Load JS 的含义。正常我们开发的 Next.js 项目，其页面表现类似于单页应用，即路由跳转（我们称之为“导航”）的时候，页面不会刷新，而会加载目标路由所需的资源然后展示。
<pre></pre>
<pre><code class="hljs language-md code-block-extension-codeShowNum">加载目标路由一共所需的 JS 大小 = 每个路由都需要依赖的 JS 大小 + 目标路由单独依赖项 JS 大小
</code></pre>
其中：
<ul>
<li>加载目标路由一共所需的 JS 大小就是 <code>First Load JS</code></li>
<li>目标路由单独依赖项 JS 大小就是 <code>Size</code></li>
<li>每个路由都需要依赖的 JS 大小就是图中单独列出来的 <code>First load JS shared by all</code></li>
</ul>
也就是说：
<pre></pre>
<pre><code class="hljs language-md code-block-extension-codeShowNum">First Load JS = Size + First load JS shared by all
</code></pre>
以上图中的 <code>/</code> 路由地址为例，89 kB（First Load JS）= 5.16 kB（Size） + 83.9 kB（First load JS shared by all）
使用官方文档中的介绍：
<ul>
<li><code>Size</code>：导航到该路由时下载的资源大小，每个路由的大小只包括它自己的依赖项</li>
<li><code>First Load JS</code>：加载该页面时下载的资源大小</li>
<li><code>First load JS shared by all</code>：所有路由共享的 JS 大小会被单独列出来</li>
</ul>
现在我们访问生产版本的 http://localhost:3000/：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7b4152d5a7a84af3be6d5d248fd2528f~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=2524&h=1004&s=469048&e=png&b=242424" alt="截屏2023-12-04 下午3.38.18.png" class="medium-zoom-image">
上图中红色框住的 JS 是每个页面都要加载的 JS，根据命令行中的输出，总共大小为 <code>83.9</code> kB，<code>413-dd2d1e77cac135ea.js</code> 和 <code>page-9a9638f75b922b0c.js</code> 是这个页面单独的 JS，总共大小为 <code>5.16</code> kB，所有JS 资源大小为 <code>89 kB</code>。（注：跟图中的数字没有完全一致是因为没有开启 gzip 压缩）
<h4 data-id="heading-13">next build --profile</h4>
该命令参数用于开启 React 的生产性能分析（需要 Next.js v9.5 以上）。
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">next build --profile
</code></pre>
然后你就可以像在开发环境中使用 React 的 <code>profiler</code> 功能。
如果你想测验这个功能，首先你的浏览器要装有 React 插件，然后你要对 React 的 Profiler API 有一定了解（其实就是测量组件渲染性能）。比如现在我们把 <code>page.js</code> 的代码改为：
<pre></pre>
<pre><code class="hljs language-jsx code-block-extension-codeShowNum">// app/page.js
import React from 'react'

export default function Page() {
return (
 <React.Profiler id="hello">
 <p>hello app server</p>
 </React.Profiler>
)
}
</code></pre>
执行 <code>npm run dev</code>，你在控制台里可以看到：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/25804df079cd4dd6ab34370bebdecfd5~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=2268&h=726&s=150520&e=png&b=292c32" alt="image.png" class="medium-zoom-image">
通常执行 <code>npm run build</code> 和 <code>npm run start</code>后，你再打开控制台，会发现在生产环境中不支持性能测量：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8ed96ece5ba946e0a1f80894f29c10be~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1984&h=754&s=133752&e=png&b=292b31" alt="image.png" class="medium-zoom-image">
但如果你执行 <code>npx next build --profile</code> 再执行 <code>npm run start</code>，尽管 React 插件会显示当前在生产环境，但 Profiler 是可以使用的：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c55d230e2aa147da831e019724815d93~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1694&h=258&s=64096&e=png&b=010101" alt="image.png" class="medium-zoom-image">
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a6de7b36eb2c4a85bd22eae7deb10aff~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=2290&h=1006&s=150923&e=png&b=292b31" alt="image.png" class="medium-zoom-image">
这个功能可以帮助大家排查线上的性能问题。
<h4 data-id="heading-14">next build --debug</h4>
该命令参数用于开启更详细的构建输出：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">next build --debug
</code></pre>
开启后，将输出额外的构建输出信息如 <code>rewrites</code>、<code>redirects</code>、<code>headers</code>。
举个例子，我们修改下 <code>next.config.js</code>文件：
<pre></pre>
<pre><code class="hljs language-javascript code-block-extension-codeShowNum">/** @type {import('next').NextConfig} */
const nextConfig = {
reactStrictMode: true,
async redirects() {
 return [
 {
 source: '/index',
 destination: '/',
 permanent: true,
 },
 ]
},
async rewrites() {
 return [
 {
 source: '/about',
 destination: '/',
 },
 ]
}
}

module.exports = nextConfig
</code></pre>
再执行 <code>npx next build --debug</code>，输出结果如下：
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/44e90f70c6654a3b9a8d0016a9fd1ea0~tplv-k3u1fbpfcp-jj-mark:1512:0:0:0:q75.awebp#?w=1106&h=1512&s=2430158&e=png&b=03070c" alt="image.png" class="medium-zoom-image">
你可以看到相比之前的构建输出信息，多了 <code>rewrites</code>、<code>redirects</code> 等信息。
<h3 data-id="heading-15">3.2. next dev</h3>
开发模式下，使用 <code>next dev</code> 运行程序，会自动具有热加载、错误报告等功能。默认情况下，程序将在 <code>http://localhost:3000</code> 开启。如果你想更改端口号：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npx next dev -p 4000
</code></pre>
如果你想更改主机名（hostname）：（以便其他主机访问）
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npx next dev -H 192.168.1.2
</code></pre>
<h3 data-id="heading-16">3.3. next start</h3>
生产模式下，使用 <code>next start</code>运行程序。不过要先执行 <code>next build</code>构建出生产代码。运行的时候，跟开发模式相同，程序默认开启在 <code>http://localhost:3000</code>。如果你想更改端口号：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">npx next start -p 4000
</code></pre>
<h3 data-id="heading-17">3.4. next lint</h3>
执行 <code>next lint</code>会为 <code>pages/</code>、<code>app/</code>、<code>components/</code>、<code>lib/</code>、<code>src/</code>目录下的所有文件执行 ESLint 语法检查。如果你没有安装 ESLint，该命令会提供一个安装指导。如果你想要指定检查的目录：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">next lint --dir utils
</code></pre>
<h3 data-id="heading-18">3.5. next info</h3>
<code>next info</code>会打印当前系统相关的信息，可用于报告 Next.js 程序的 bug。在项目的根目录中执行：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">next info
</code></pre>
打印信息类似于：
<pre></pre>
<pre><code class="hljs language-bash code-block-extension-codeShowNum">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
</code></pre>
这些信息可以贴到 GitHub Issues 中方便 Next.js 官方人员排查问题。
<h2 data-id="heading-19">小结</h2>
恭喜你，完成本篇内容的学习！
这一节我们讲解了自动创建项目和手动创建项目两种创建项目的方式，如果是全新的项目，推荐使用自动创建方式。如果是项目中引入 Next.js，可以参考手动创建项目的方式。
Next.js 项目常用的脚本有三个：<code>npm run dev</code>用于开发时使用、<code>npm run build</code>用于构建生产版本、<code>npm run start</code>用于运行生产版本。
从 <code>package.json</code>中，我们得知这些脚本背后用的其实是 Next.js CLI 的 <code>next</code> 命令，然后我们对常用的 <code>next</code> 命令和相关参数进行了介绍。在必要的时候，可以使用这些命令和参数自定义 npm 脚本。
靡不有初，鲜克有终。恭喜你迈出第一步！接下来我们将进入路由篇，带大家了解 Next.js v13 带来颠覆式更新的的 App Route 功能。在学习的过程中，如果遇到有疑问的地方，一定要多写 demo 测试哦！
 
 
知识星球【Next.js开发指南】（已更新至第33章）
<ol>
<li>初始篇 | Next.js CLI</li>
<li>路由篇 | App Router</li>
<li>路由篇 | 动态路由、路由组、平行路由和拦截路由</li>
<li>路由篇 | 路由处理程序和中间件</li>
<li>路由篇 | 国际化</li>
<li>数据获取篇 | 数据获取、缓存与重新验证</li>
<li>数据获取篇 | Server Actions 与表单</li>
<li>渲染篇 | 从 CSR、SSR、SSG、ISR 开始说起</li>
<li>渲染篇 | 服务端组件和客户端组件</li>
<li>渲染篇 | Streaming 和 Edge Runtime</li>
<li>缓存篇 | Caching</li>
<li>样式篇 | Tailwind CSS、CSS-in-JS 与 Sass</li>
<li>组件篇 | Images</li>
<li>组件篇 | Font</li>
<li>组件篇 | Link 和 Script</li>
<li>优化篇 | 懒加载</li>
<li>配置篇 | TypeScript 和 ESLint</li>
<li>配置篇 | 环境变量、路径别名与 src 目录</li>
<li>配置篇 | MDX</li>
<li>配置篇 | 草稿模式和内容安全策略</li>
<li>配置篇 | 路由段配置项</li>
<li>部署篇 | 静态导出</li>
<li>Metadata 篇 | 基于配置</li>
<li>Metadata 篇 | 基于文件</li>
<li>API 篇 | next.config.js（上）</li>
<li>API 篇 | next.config.js（下）</li>
<li>API 篇 | 请求相关的常用函数与方法</li>
<li>API 篇 | 常用函数与方法</li>
<li>实战篇 | React Notes | 项目介绍与创建</li>
<li>实战篇 | React Notes | 侧边栏笔记列表</li>
<li>实战篇 | React Notes | 笔记预览界面</li>
<li>实战篇 | React Notes | 笔记编辑界面</li>
<li>实战篇 | React Notes | 笔记搜索</li>
<li>实战篇 | React Notes | 国际化</li>
<li>实战篇 | React Notes | Auth</li>
<li>实战篇 | React Notes | 文件上传</li>
<li>实战篇 | React Notes | 部署（一）</li>
<li>实战篇 | React Notes | 部署（二）</li>
<li>实战篇 | 博客 | 项目创建</li>
<li>实战篇 | 博客 | 博客后台</li>
<li>实战篇 | 博客 | MDX</li>
<li>实战篇 | 博客 | Server Actions</li>
<li>实战篇 | 博客 | 渲染原理</li>
<li>实战篇 | App | 需求分析</li>
<li>实战篇 | App | 数据库设计</li>
<li>实战篇 | App | 项目创建</li>
<li>实战篇 | App | 移动端处理</li>
<li>实战篇 | App | 接口开发</li>
<li>实战篇 | App | 数据请求</li>
<li>实战篇 | App | 构建部署</li>
<li>源码篇 | 源码架构</li>
<li>源码篇 | 调试代码</li>
<li>源码篇 | 路由实现</li>
<li>源码篇 | 渲染原理</li>
<li>源码篇 | 手写 SSR</li>
<li>源码篇 | mini-next</li>
<li>源码篇 | mini-next</li>
<li>源码篇 | mini-next</li>
<li>源码篇 | mini-next</li>
<li>面试篇 | 常见面试题及解析</li>
<li>面试篇 | 常见面试题及解析</li>
<li>面试篇 | 常见面试题及解析</li>
</ol></div> 
来源：https://www.cnblogs.com/silva/p/17948720

頁: [1]

琼殿技术论坛's Archiver

Next.js 开发指南 初始篇 | Next.js CLI

Next.js 开发指南初始篇 | Next.js CLI