1
1
---
2
- source-updated-at : ' 2025-05-16T04:52:11 .000Z'
3
- translation-updated-at : ' 2025-05-17T02:12:53.432Z '
2
+ source-updated-at : 2025-05-21T18:33:43 .000Z
3
+ translation-updated-at : 2025-05-21T19:18:02.138Z
4
4
title : 如何新建 Next.js 项目
5
5
nav_title : 安装指南
6
6
description : 使用 `create-next-app` CLI 创建新的 Next.js 应用,并配置 TypeScript、ESLint 和模块路径别名。
7
7
---
8
8
9
- { /* 本文档内容在应用路由和页面路由间共享。可使用 `<PagesOnly>内容</PagesOnly>` 组件添加仅适用于页面路由的内容。任何共享内容不应包裹在组件中 。*/ }
9
+ { /* 本文档内容在应用路由和页面路由间共享。如需添加仅适用于页面路由的内容, 可使用 `<PagesOnly>内容</PagesOnly>` 组件。共享内容不应包裹在任何组件中 。*/ }
10
10
11
11
## 系统要求
12
12
13
13
开始前请确保系统满足以下要求:
14
14
15
15
- [ Node.js 18.18] ( https://nodejs.org/ ) 或更高版本
16
- - macOS、Windows(含 WSL)或 Linux
16
+ - macOS、Windows(含 WSL)或 Linux 系统
17
17
18
18
## 自动安装
19
19
20
- 创建 Next.js 应用最快的方式是使用 [ ` create-next-app ` ] ( /docs/app/api-reference/cli/create-next-app ) ,它会自动完成所有设置 。运行以下命令创建项目:
20
+ 创建 Next.js 应用最快的方式是使用 [ ` create-next-app ` ] ( /docs/app/api-reference/cli/create-next-app ) ,它会自动完成所有配置 。运行以下命令创建项目:
21
21
22
22
``` bash filename="终端"
23
23
npx create-next-app@latest
@@ -26,18 +26,18 @@ npx create-next-app@latest
26
26
安装过程中会看到以下提示:
27
27
28
28
``` txt filename="终端"
29
- 项目名称是什么 ?my-app
29
+ 请输入项目名称 ?my-app
30
30
是否使用 TypeScript?否 / 是
31
31
是否使用 ESLint?否 / 是
32
32
是否使用 Tailwind CSS?否 / 是
33
- 是否将代码放在 `src/` 目录中 ?否 / 是
34
- 是否使用 App Router? (推荐)否 / 是
33
+ 是否将代码放在 `src/` 目录下 ?否 / 是
34
+ 是否使用应用路由 (推荐)? 否 / 是
35
35
是否在 `next dev` 中使用 Turbopack?否 / 是
36
36
是否自定义导入别名(默认为 `@/*`)?否 / 是
37
- 要配置什么导入别名 ?@/*
37
+ 请输入配置的导入别名 ?@/*
38
38
```
39
39
40
- 完成提示后,[ ` create-next-app ` ] ( /docs/app/api-reference/cli/create-next-app ) 会创建以项目名命名的文件夹并安装所需依赖 。
40
+ 完成提示后,[ ` create-next-app ` ] ( /docs/app/api-reference/cli/create-next-app ) 会创建项目文件夹并安装所需依赖 。
41
41
42
42
## 手动安装
43
43
@@ -65,7 +65,7 @@ npm install next@latest react@latest react-dom@latest
65
65
- ` next dev ` :启动开发服务器
66
66
- ` next build ` :构建生产环境应用
67
67
- ` next start ` :启动生产服务器
68
- - ` next lint ` :运行 ESLint
68
+ - ` next lint ` :运行 ESLint 检查
69
69
70
70
<AppOnly >
71
71
@@ -103,20 +103,20 @@ export default function RootLayout({ children }) {
103
103
104
104
``` tsx filename="app/page.tsx" switcher
105
105
export default function Page() {
106
- return <h1 >Hello, Next.js! </h1 >
106
+ return <h1 >你好, Next.js! </h1 >
107
107
}
108
108
```
109
109
110
110
``` jsx filename="app/page.js" switcher
111
111
export default function Page () {
112
- return < h1> Hello, Next .js ! < / h1>
112
+ return < h1> 你好, Next .js ! < / h1>
113
113
}
114
114
```
115
115
116
- 当用户访问应用根路径 (` / ` ) 时,` layout.tsx ` 和 ` page.tsx ` 会被渲染 。
116
+ 当用户访问应用根路径 (` / ` ) 时,` layout.tsx ` 和 ` page.tsx ` 将同时渲染 。
117
117
118
118
<Image
119
- alt = " App 文件夹结构 "
119
+ alt = " 应用目录结构 "
120
120
srcLight = " /docs/light/app-getting-started.png"
121
121
srcDark = " /docs/dark/app-getting-started.png"
122
122
width = " 1600"
@@ -125,8 +125,8 @@ export default function Page() {
125
125
126
126
> ** 须知** :
127
127
>
128
- > - 如果忘记创建根布局,运行 ` next dev ` 启动开发服务器时 Next.js 会自动创建该文件
129
- > - 可选择在项目根目录使用 [ ` src ` 文件夹] ( /docs/app/api-reference/file-conventions/src-folder ) 来分离应用代码和配置文件
128
+ > - 如果忘记创建根布局,运行 ` next dev ` 启动开发服务器时 Next.js 会自动生成
129
+ > - 可选择使用项目根目录下的 [ ` src ` 文件夹] ( /docs/app/api-reference/file-conventions/src-folder ) 来分离应用代码和配置文件
130
130
131
131
</AppOnly >
132
132
@@ -136,21 +136,21 @@ export default function Page() {
136
136
137
137
Next.js 使用文件系统路由,意味着应用路由由文件结构决定。
138
138
139
- 在项目根目录创建 ` pages ` 文件夹,然后添加 ` index.tsx ` 文件作为首页 (` / ` ):
139
+ 在项目根目录创建 ` pages ` 文件夹,然后添加 ` index.tsx ` 作为首页 (` / ` ):
140
140
141
141
``` tsx filename="pages/index.tsx" switcher
142
142
export default function Page() {
143
- return <h1 >Hello, Next.js! </h1 >
143
+ return <h1 >你好, Next.js! </h1 >
144
144
}
145
145
```
146
146
147
147
``` jsx filename="pages/index.js" switcher
148
148
export default function Page () {
149
- return < h1> Hello, Next .js ! < / h1>
149
+ return < h1> 你好, Next .js ! < / h1>
150
150
}
151
151
```
152
152
153
- 接着在 ` pages/ ` 中添加 ` _app.tsx ` 文件定义全局布局 。了解更多关于[ 自定义 App 文件] ( /docs/pages/building-your-application/routing/custom-app ) 。
153
+ 接着在 ` pages/ ` 下添加 ` _app.tsx ` 定义全局布局 。了解更多关于[ 自定义 App 文件] ( /docs/pages/building-your-application/routing/custom-app ) 。
154
154
155
155
``` tsx filename="pages/_app.tsx" switcher
156
156
import type { AppProps } from ' next/app'
@@ -166,7 +166,7 @@ export default function App({ Component, pageProps }) {
166
166
}
167
167
```
168
168
169
- 最后在 ` pages/ ` 中添加 ` _document.tsx ` 文件控制服务器初始响应 。了解更多关于[ 自定义 Document 文件] ( /docs/pages/building-your-application/routing/custom-document ) 。
169
+ 最后在 ` pages/ ` 下添加 ` _document.tsx ` 控制服务器初始响应 。了解更多关于[ 自定义 Document 文件] ( /docs/pages/building-your-application/routing/custom-document ) 。
170
170
171
171
``` tsx filename="pages/_document.tsx" switcher
172
172
import { Html , Head , Main , NextScript } from ' next/document'
@@ -204,49 +204,49 @@ export default function Document() {
204
204
205
205
### 创建 ` public ` 文件夹(可选)
206
206
207
- 在项目根目录创建 [ ` public ` 文件夹] ( /docs/app/api-reference/file-conventions/public-folder ) 存放图片、字体等静态资源 。` public ` 内的文件可通过根路径 (` / ` ) 引用。
207
+ 在项目根目录创建 [ ` public ` 文件夹] ( /docs/app/api-reference/file-conventions/public-folder ) 存放静态资源(如图片、字体等) 。` public ` 中的文件可通过根路径 (` / ` ) 引用。
208
208
209
209
例如 ` public/profile.png ` 可引用为 ` /profile.png ` :
210
210
211
211
``` tsx filename="app/page.tsx" highlight={4} switcher
212
212
import Image from ' next/image'
213
213
214
214
export default function Page() {
215
- return <Image src = " /profile.png" alt = " Profile " width = { 100 } height = { 100 } />
215
+ return <Image src = " /profile.png" alt = " 个人头像 " width = { 100 } height = { 100 } />
216
216
}
217
217
```
218
218
219
219
``` jsx filename="app/page.js" highlight={4} switcher
220
220
import Image from ' next/image'
221
221
222
222
export default function Page () {
223
- return < Image src= " /profile.png" alt= " Profile " width= {100 } height= {100 } / >
223
+ return < Image src= " /profile.png" alt= " 个人头像 " width= {100 } height= {100 } / >
224
224
}
225
225
```
226
226
227
227
## 运行开发服务器
228
228
229
- 1 . 运行 ` npm run dev ` 启动开发服务器
229
+ 1 . 执行 ` npm run dev ` 启动开发服务器
230
230
2 . 访问 ` http://localhost:3000 ` 查看应用
231
- 3 . 编辑<AppOnly >` app/page.tsx ` </AppOnly > <PagesOnly >` pages/index.tsx ` </PagesOnly > 文件并保存,浏览器中即可看到更新结果
231
+ 3 . 编辑 <AppOnly >` app/page.tsx ` </AppOnly ><PagesOnly >` pages/index.tsx ` </PagesOnly > 文件并保存,浏览器中即可看到更新结果
232
232
233
233
## 配置 TypeScript
234
234
235
- > 最低 TypeScript 版本要求 :` v4.5.2 `
235
+ > TypeScript 最低版本要求 :` v4.5.2 `
236
236
237
- Next.js 内置 TypeScript 支持。要添加 TypeScript 到项目 ,只需将文件重命名为 ` .ts ` / ` .tsx ` 并运行 ` next dev ` 。Next.js 会自动安装必要依赖并添加包含推荐配置的 ` tsconfig.json ` 文件。
237
+ Next.js 内置 TypeScript 支持。要将 TypeScript 添加到项目 ,只需将文件重命名为 ` .ts ` / ` .tsx ` 并运行 ` next dev ` 。Next.js 会自动安装必要依赖并创建包含推荐配置的 ` tsconfig.json ` 文件。
238
238
239
239
<AppOnly >
240
240
241
241
### IDE 插件
242
242
243
- Next.js 包含自定义 TypeScript 插件和类型检查器,可供 VSCode 等代码编辑器实现高级类型检查和自动补全 。
243
+ Next.js 包含自定义 TypeScript 插件和类型检查器,可供 VSCode 等编辑器实现高级类型检查和自动补全 。
244
244
245
245
在 VS Code 中启用插件:
246
246
247
247
1 . 打开命令面板 (` Ctrl/⌘ ` + ` Shift ` + ` P ` )
248
- 2 . 搜索 "TypeScript: Select TypeScript Version "
249
- 3 . 选择 "Use Workspace Version "
248
+ 2 . 搜索 "TypeScript: 选择 TypeScript 版本 "
249
+ 3 . 选择 "使用工作区版本 "
250
250
251
251
<Image
252
252
alt = " TypeScript 命令面板"
@@ -258,13 +258,13 @@ Next.js 包含自定义 TypeScript 插件和类型检查器,可供 VSCode 等
258
258
259
259
</AppOnly >
260
260
261
- 更多信息请参考 [ TypeScript 参考文档 ] ( /docs/app/api-reference/config/next-config-js/typescript ) 。
261
+ 更多信息请参考 [ TypeScript 配置文档 ] ( /docs/app/api-reference/config/next-config-js/typescript ) 。
262
262
263
263
## 配置 ESLint
264
264
265
- Next.js 内置 ESLint 支持。使用 ` create-next-app ` 创建新项目时会自动安装必要包并配置正确设置 。
265
+ Next.js 内置 ESLint 支持。使用 ` create-next-app ` 创建项目时会自动安装必要包并配置正确设置 。
266
266
267
- 要为现有项目手动添加 ESLint,在 ` package.json ` 中添加 ` next lint ` 脚本:
267
+ 要为现有项目手动添加 ESLint,请在 ` package.json ` 中添加 ` next lint ` 脚本:
268
268
269
269
``` json filename="package.json"
270
270
{
@@ -274,35 +274,35 @@ Next.js 内置 ESLint 支持。使用 `create-next-app` 创建新项目时会自
274
274
}
275
275
```
276
276
277
- 然后运行 ` npm run lint ` ,将引导完成安装和配置流程 :
277
+ 然后运行 ` npm run lint ` ,安装向导将引导完成配置过程 :
278
278
279
279
``` bash filename="终端"
280
280
npm run lint
281
281
```
282
282
283
- 您会看到如下提示 :
283
+ 您将看到如下提示 :
284
284
285
- > ? 您希望如何配置 ESLint?
285
+ > ? 希望如何配置 ESLint?
286
286
>
287
287
> ❯ 严格模式(推荐)
288
288
> 基础模式
289
289
> 取消
290
290
291
- - ** 严格模式** :包含 Next.js 基础 ESLint 配置及更严格的 Core Web Vitals 规则集。初次设置 ESLint 时推荐此配置
291
+ - ** 严格模式** :包含 Next.js 基础 ESLint 配置及更严格的 Core Web Vitals 规则集。首次配置 ESLint 时推荐使用
292
292
- ** 基础模式** :仅包含 Next.js 基础 ESLint 配置
293
- - ** 取消** :跳过配置。如计划自定义 ESLint 配置请选此项
293
+ - ** 取消** :跳过配置。如需自定义 ESLint 配置请选择此项
294
294
295
295
选择"严格"或"基础"后,Next.js 会自动安装 ` eslint ` 和 ` eslint-config-next ` 依赖,并在项目根目录创建包含所选配置的 ` .eslintrc.json ` 文件。
296
296
297
- 现在可随时运行 ` next lint ` 执行 ESLint 检查。ESLint 设置完成后 ,每次构建 (` next build ` ) 时也会自动运行。错误会导致构建失败,而警告不会。
297
+ 此后可通过运行 ` next lint ` 执行 ESLint 检查。ESLint 配置完成后 ,每次构建 (` next build ` ) 时也会自动运行。错误会导致构建失败,而警告不会。
298
298
299
299
更多信息请参考 [ ESLint 插件文档] ( /docs/app/api-reference/config/next-config-js/eslint ) 。
300
300
301
301
## 配置绝对导入和模块路径别名
302
302
303
- Next.js 原生支持 ` tsconfig.json ` 和 ` jsconfig.json ` 文件中的 ` "paths" ` 和 ` "baseUrl" ` 选项。
303
+ Next.js 原生支持 ` tsconfig.json ` 和 ` jsconfig.json ` 中的 ` "paths" ` 和 ` "baseUrl" ` 选项。
304
304
305
- 这些选项允许将项目目录别名化为绝对路径,使模块导入更简洁 。例如:
305
+ 这些选项允许将项目目录映射为绝对路径,使模块导入更清晰简洁 。例如:
306
306
307
307
``` jsx
308
308
// 之前
@@ -312,7 +312,7 @@ import { Button } from '../../../components/button'
312
312
import { Button } from ' @/components/button'
313
313
```
314
314
315
- 要配置绝对导入,在 ` tsconfig.json ` 或 ` jsconfig.json ` 中添加 ` baseUrl ` 配置选项。例如 :
315
+ 要配置绝对导入,请在 ` tsconfig.json ` 或 ` jsconfig.json ` 中添加 ` baseUrl ` 配置 :
316
316
317
317
``` json filename="tsconfig.json 或 jsconfig.json"
318
318
{
@@ -322,7 +322,7 @@ import { Button } from '@/components/button'
322
322
}
323
323
```
324
324
325
- 除配置 ` baseUrl ` 路径外 ,还可使用 ` "paths" ` 选项设置模块路径"别名"。
325
+ 除配置 ` baseUrl ` 外 ,还可使用 ` "paths" ` 选项设置模块路径"别名"。
326
326
327
327
例如以下配置将 ` @/components/* ` 映射到 ` components/* ` :
328
328
@@ -338,4 +338,4 @@ import { Button } from '@/components/button'
338
338
}
339
339
```
340
340
341
- 每个 ` "paths" ` 都相对于 ` baseUrl ` 位置 。
341
+ 每个 ` "paths" ` 都相对于 ` baseUrl ` 指定的位置 。
0 commit comments