【Next.js】001-项目初始化
文章目录
- 【Next.js】001-项目初始化
- 一、前言
- 二、自动创建项目
- 1、环境要求
- 2、创建项目
- 创建命令
- 创建演示
- 生成的项目目录
- 如果你不使用 `npx` 命令
- 3、运行项目
- 脚本说明
- 在开发环境运行项目
- 查看页面
- 4、示例代码
- 说明
- 创建项目
- 查看示例项目
- 创建项目命令
- 创建过程
- 运行结果
- 三、手动创建项目
- 第一步：创建文件夹并安装依赖
- 第二步：添加 scripts
- 第三步：创建目录和文件
- 第四步：运行项目
- 四、Next.js CLI
- 1、说明
- 2、next build
- 命令解析
- 启动生产版本
- next build --profile
- next build --debug
- 3、next dev
- 4、next start
- 5、next lint
- 6、next info
- 五、参考链接
一、前言
訾博自述：
AI 时代，我觉得 Next.js 能满足轻量、快速、灵活的需求！
2024年12月28日
首先，让我们学会创建一个 Next.js 项目！Next.js 提供了开箱即用的 create-next-app脚手架，内置支持 TypeScript、ESLint 等功能，零配置即可实现自动编译和打包。
本文包括：自动创建项目和手动创建项目，以及开发项目时常用的脚本命令。
二、自动创建项目
1、环境要求
我学习的时候，老师的版本是 14 ，我使用的版本是 15.1.3 ，老师没使用 TypeScript ，我使用了！
有些地方，如老师所言“减轻学习负担”，没有使用 TypeScript ！
Next.js v14 版本，需要 Node.js 18.17 及以后版本。
2、创建项目
创建命令
使用开箱即用的
create-next-app脚手架。
npx create-next-app@latest
创建演示
C:\MyFile\NextJsProjects>npx create-next-app@latest
Need to install the following packages:
create-next-app@15.1.3
Ok to proceed? (y) y
√ What is your project named? ... hello-next-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 your code inside a `src/` directory? ... No / Yes
√ Would you like to use App Router? (recommended) ... No / Yes
√ Would you like to use Turbopack for `next dev`? ... No / Yes
√ Would you like to customize the import alias (`@/*` by default)? ... No / Yes
Creating a new Next.js app in C:\MyFile\NextJsProjects\hello-next-app.
生成的项目目录
如果你不使用 npx 命令
如果你不使用
npx，也支持使用yarn、npm、bunx，下面三选一：
yarn create next-app
npm create next-app
bunx create-next-app
3、运行项目
脚本说明
查看项目根目录 package.json 文件的代码：
"scripts": {
"dev": "next dev --turbopack",
"build": "next build",
"start": "next start",
"lint": "next lint"
},
说明：开发的时候使用 npm run dev。部署的时候先使用 npm run build 构建生产代码，再执行 npm run start 运行生产项目。运行 npm run lint 则会执行 ESLint 语法检查。
在开发环境运行项目
PS C:\MyFile\NextJsProjects\hello-next-app> npm run dev
> hello-next-app@0.1.0 dev C:\MyFile\NextJsProjects\hello-next-app
> next dev --turbopack
▲ Next.js 15.1.3 (Turbopack)
- Local: http://localhost:3000
- Network: http://198.18.0.1:3000
✓ Starting...
✓ Ready in 1100m
查看页面
访问：http://localhost:3000
注：学习的时候为了避免浏览器插件带来的影响，建议在无痕模式下测试。
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 搭配使用。
可以访问 https://github.com/vercel/next.js/tree/canary/examples 查看有哪些示例代码。如果你想直接使用某个示例代码，就比如 with-redux，无须手动 clone 代码，在创建项目的时候使用 --example 参数即可直接创建：
npx create-next-app --example with-redux your-app-name
注：使用示例代码的时候，并不会像执行 npx create-next-app时提示是否使用 TypeScript、ESLint 等，而是会直接进入项目创建和依赖安装阶段。
创建项目
查看示例项目
还是在这里做一个演示吧，怕以后没机会！
创建项目命令
npx create-next-app --example with-next-ui hello-next-app-with-next-ui
创建过程
C:\MyFile\NextJsProjects>npx create-next-app --example with-next-ui hello-next-app-with-next-ui
Need to install the following packages:
create-next-app@15.1.3
Ok to proceed? (y) y
Creating a new Next.js app in C:\MyFile\NextJsProjects\hello-next-app-with-next-ui.
Downloading files for example with-next-ui. This might take a moment.
Installing packages. This might take a couple of minutes.
added 144 packages in 19s
5 packages are looking for funding
run `npm fund` for details
Initialized a git repository.
Success! Created hello-next-app-with-next-ui at C:\MyFile\NextJsProjects\hello-next-app-with-next-ui
Inside that directory, you can run several commands:
npm run dev
Starts the development server.
npm run build
Builds the app for production.
npm start
Runs the built app in production mode.
We suggest that you begin by typing:
cd hello-next-app-with-next-ui
npm run dev
运行结果
npm run dev
http://localhost:3000
(我把上面主项目停了)
三、手动创建项目
大部分时候我们并不需要手动创建 Next.js 项目，但了解这个过程有助于我们认识到一个最基础的 Next.js 项目依赖哪些东西。
第一步：创建文件夹并安装依赖
现在，创建一个文件夹，假设名为 next-app-manual，cd 进入该目录，安装依赖：
npm install next@latest react@latest react-dom@latest
npm 会自动创建 package.json 并安装依赖项。
C:\MyFile\NextJsProjects\next-app-manual>npm install next@latest react@latest react-dom@latest
added 28 packages in 13s
5 packages are looking for funding
run `npm fund` for details
当前目录
第二步：添加 scripts
打开 package.json，添加以下内容：
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
}
}
当前的文件
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
},
"dependencies": {
"next": "^15.1.3",
"react": "^19.0.0",
"react-dom": "^19.0.0"
}
}
第三步：创建目录和文件
在 next-app-manual下新建 app 文件夹，app 下新建 layout.js 和 page.js文件，代码如下：
layout.js
// app/layout.ts
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}
page.js
// app/page.js
export default function Page() {
return <h1>Hello, Next.js!</h1>;
}
第四步：运行项目
现在运行 npm run dev，正常渲染则表示运行成功：
我关闭了其他项目！
http://localhost:3000
四、Next.js CLI
1、说明
通过 package.json 中的代码我们知道：当我们运行 npm run dev 的时候，其实执行的是 next dev。next 命令就是来自于 Next.js CLI。Next.js CLI 可以帮助你启动、构建和导出项目。
完整的 CLI 命令，你可以执行 npx next -h 查看（-h 是 --help 的简写）。
C:\MyFile\NextJsProjects\next-app-manual>npx next -h
Usage: next [options] [command]
The Next.js CLI allows you to develop, build, start your application, and more.
Options:
-v, --version Outputs the Next.js version.
-h, --help Displays this message.
Commands:
build [directory] [options] Creates an optimized production build of your application. The output
displays information about each route.
dev [directory] [options] Starts Next.js in development mode with hot-code reloading, error reporting,
and more.
info [options] Prints relevant details about the current system which can be used to report
Next.js bugs.
lint [directory] [options] Runs ESLint for all files in the `/src`, `/app`, `/pages`, `/components`,
and `/lib` directories. It also provides a guided setup to install any
required dependencies if ESLint is not already configured in your
application.
start [directory] [options] Starts Next.js in production mode. The application should be compiled with
`next build` first.
telemetry [options] [arg] Allows you to enable or disable Next.js' completely anonymous
telemetry collection.
experimental-test [directory] [options] Execute `next/experimental/testmode` tests using a specified test runner.
The test runner defaults to 'playwright' if the
`experimental.defaultTestRunner` configuration option or the `--test-runner`
option are not set.
internal [options] [command] Internal debugging commands. Use with caution. Not covered by semver.
C:\MyFile\NextJsProjects\next-app-manual>
从上面代码可以看到，next 可以执行的命令有多个，我们介绍下最常用的一些。
注：因为我们是使用 npx创建的项目，这种方式下避免了全局安装 create-next-app，所以我们本地全局并无 next 命令。如果你要执行 next 命令，可以在 next前加一个 npx，就比如这次用到的 npx next -h
2、next build
命令解析
执行 next build 将会创建项目的生产优化版本：
npx next build
这里我们基于最上面自动创建的项目执行命令！
PS C:\MyFile\NextJsProjects\hello-next-app> npx next build
▲ Next.js 15.1.3
Creating an optimized production build ...
✓ Compiled successfully
✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (5/5)
✓ Collecting build traces
✓ Finalizing page optimization
Route (app) Size First Load JS
┌ ○ / 5.49 kB 111 kB
└ ○ /_not-found 979 B 106 kB
+ First Load JS shared by all 105 kB
├ chunks/4bd1b696-20882bf820444624.js 52.9 kB
├ chunks/517-c2114bf3c23dacd6.js 50.5 kB
└ other shared chunks (total) 1.95 kB
○ (Static) prerendered as static content
PS C:\MyFile\NextJsProjects\hello-next-app>
可以看出，构建时会输出每条路由的信息，比如 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
使用官方文档中的介绍就是：
Size：导航到该路由时下载的资源大小，每个路由的大小只包括它自己的依赖项First Load JS：加载该页面时下载的资源大小First load JS shared by all：所有路由共享的 JS 大小会被单独列出来
启动生产版本
npm run start
此时我关闭了其他正在运行的项目，保证 3000 端口是不被占用的！
PS C:\MyFile\NextJsProjects\hello-next-app> npm run start
> hello-next-app@0.1.0 start
> next start
▲ Next.js 15.1.3
- Local: http://localhost:3000
- Network: http://198.18.0.1:3000
✓ Starting...
✓ Ready in 475ms
访问页面
next build --profile
该命令参数用于开启 React 的生产性能分析（需要 Next.js v9.5 以上）。
npx next build --profile
然后就可以像在开发环境中使用 React 的 profiler 功能了。
注：这里我们执行的命令是
npx next build --profile，而不是npm run build --profile。实际上有三种方式可以开启：
运行
npx next build --profile先修改
package.json中的build脚本命令为：{ "scripts": { "build": "next build --profile" } }然后再运行
npm run build运行
npm run build -- --profile，将--profile添加到--分隔符后，会将--profile作为参数传递给实际执行的命令，最终的命令还是next build --profile下面的
--debug参数使用也是同理！
如果想测验这个功能，首先你的浏览器要装有 React 插件，然后你要对 React 的 Profiler API 有一定了解（其实就是测量组件渲染性能）。比如现在我们把 page.js 的代码改为：
// app/page.js
import React from 'react'
export default function Page() {
return (
<React.Profiler id="hello">
<p>hello app server</p>
</React.Profiler>
)
}
注意这是 next-app-manual 项目！
通常执行 npm run build 和 npm run start后，你再打开控制台，会发现在生产环境中不支持性能测量，但如果你执行 npx next build --profile 再执行 npm run start，尽管 React 插件会显示当前在生产环境，但 Profiler 是可以使用的。这个功能可以帮助排查线上的性能问题。
next build --debug
该命令参数用于开启更详细的构建输出：
npx next build --debug
开启后，将输出额外的构建输出信息如 rewrites、redirects、headers。
举个例子，我们修改下 next.config.ts文件：
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
/* config options here */
reactStrictMode: true,
async redirects() {
return [
{
source: '/index',
destination: '/',
permanent: true,
},
]
},
async rewrites() {
return [
{
source: '/about',
destination: '/',
},
]
}
};
export default nextConfig;
再执行 npx next build --debug，输出结果如下：
PS C:\MyFile\NextJsProjects\hello-next-app> npx next build --debug
▲ Next.js 15.1.3
Creating an optimized production build ...
✓ Compiled successfully
✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (5/5)
✓ Collecting build traces
✓ Finalizing page optimization
Redirects
┌ source: /:path+/
├ destination: /:path+
└ permanent: true
┌ source: /index
├ destination: /
└ permanent: true
Rewrites
┌ source: /about
└ destination: /
Route (app) Size First Load JS
┌ ○ / 5.49 kB 111 kB
└ ○ /_not-found 979 B 106 kB
+ First Load JS shared by all 105 kB
├ chunks/4bd1b696-20882bf820444624.js 52.9 kB
├ chunks/517-2c39ce28bcba308e.js 50.5 kB
└ other shared chunks (total) 1.95 kB
○ (Static) prerendered as static content
PS C:\MyFile\NextJsProjects\hello-next-app>
可以看到相比之前的构建输出信息，多了 rewrites、redirects 等信息。关于 rewrites、redirects 的具体用法，我们会在后续的内容中介绍。
3、next dev
开发模式下，使用 next dev 运行程序，会自动具有热加载、错误报告等功能。默认情况下，程序将在 http://localhost:3000 开启。如果你想更改端口号：
npx next dev -p 4000
如果你想更改主机名（hostname）：（以便其他主机访问）
npx next dev -H 192.168.1.2
4、next start
生产模式下，使用 next start运行程序。不过要先执行 next build构建出生产代码。运行的时候，跟开发模式相同，程序默认开启在 http://localhost:3000。如果你想更改端口号：
npx next start -p 4000
5、next lint
执行 next lint会为 pages/、app/、components/、lib/、src/目录下的所有文件执行 ESLint 语法检查。如果你没有安装 ESLint，该命令会提供一个安装指导。如果你想要指定检查的目录：
npx next lint --dir app
执行演示
PS C:\MyFile\NextJsProjects\hello-next-app> npx next lint --dir app
✔ No ESLint warnings or errors
PS C:\MyFile\NextJsProjects\hello-next-app>
6、next info
next info会打印当前系统相关的信息，可用于报告 Next.js 程序的 bug。在项目的根目录中执行：
npx next info
执行演示
PS C:\MyFile\NextJsProjects\hello-next-app> npx next info
'yarn' �����ڲ����ⲿ���Ҳ���ǿ����еij���
�������ļ�
Operating System:
Platform: win32
Arch: x64
Version: Windows 11 IoT Enterprise LTSC 2024
Available memory (MB): 24399
Available CPU cores: 16
Binaries:
Node: 20.18.0
npm: 10.8.2
Yarn: N/A
pnpm: 9.15.1
Relevant Packages:
next: 15.1.3 // Latest available version is detected (15.1.3).
eslint-config-next: 15.1.3
react: 19.0.0
react-dom: 19.0.0
typescript: 5.7.2
Next.js Config:
output: N/A
PS C:\MyFile\NextJsProjects\hello-next-app>
这些信息可以贴到 GitHub Issues 中方便 Next.js 官方人员排查问题。
五、参考链接
- Getting Started: Installation
- API Reference: create-next-app
- API Reference: Next.js CLI
- npm-run-script
