Skip to content

Commit bbca86f

Browse files
xiaoyu2erxiaoyu2er
committed
feat: update translation documentations
1 parent b4aa653 commit bbca86f

14 files changed

+3924
-0
lines changed

‎apps/docs/content/zh-hans/docs/01-app/01-getting-started/01-installation.mdx

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
source-updated-at: '2025-05-16T04:52:11.000Z'
3+
translation-updated-at: '2025-05-17T02:12:53.432Z'
4+
title: 如何新建 Next.js 项目
5+
nav_title: 安装指南
6+
description: 使用 `create-next-app` CLI 创建新的 Next.js 应用，并配置 TypeScript、ESLint 和模块路径别名。
7+
---
8+
9+
{/* 本文档内容在应用路由和页面路由间共享。可使用 `<PagesOnly>内容</PagesOnly>` 组件添加仅适用于页面路由的内容。任何共享内容不应包裹在组件中。*/}
10+
11+
## 系统要求
12+
13+
开始前请确保系统满足以下要求：
14+
15+
- [Node.js 18.18](https://nodejs.org/) 或更高版本
16+
- macOS、Windows（含 WSL）或 Linux
17+
18+
## 自动安装
19+
20+
创建 Next.js 应用最快的方式是使用 [`create-next-app`](/docs/app/api-reference/cli/create-next-app)，它会自动完成所有设置。运行以下命令创建项目：
21+
22+
```bash filename="终端"
23+
npx create-next-app@latest
24+
```
25+
26+
安装过程中会看到以下提示：
27+
28+
```txt filename="终端"
29+
项目名称是什么？my-app
30+
是否使用 TypeScript？否 / 是
31+
是否使用 ESLint？否 / 是
32+
是否使用 Tailwind CSS？否 / 是
33+
是否将代码放在 `src/` 目录中？否 / 是
34+
是否使用 App Router？（推荐）否 / 是
35+
是否在 `next dev` 中使用 Turbopack？否 / 是
36+
是否自定义导入别名（默认为 `@/*`）？否 / 是
37+
要配置什么导入别名？@/*
38+
```
39+
40+
完成提示后，[`create-next-app`](/docs/app/api-reference/cli/create-next-app) 会创建以项目名命名的文件夹并安装所需依赖。
41+
42+
## 手动安装
43+
44+
要手动创建 Next.js 应用，请先安装必要包：
45+
46+
```bash filename="终端"
47+
npm install next@latest react@latest react-dom@latest
48+
```
49+
50+
然后在 `package.json` 中添加以下脚本：
51+
52+
```json filename="package.json"
53+
{
54+
"scripts": {
55+
"dev": "next dev",
56+
"build": "next build",
57+
"start": "next start",
58+
"lint": "next lint"
59+
}
60+
}
61+
```
62+
63+
这些脚本对应应用开发的不同阶段：
64+
65+
- `next dev`：启动开发服务器
66+
- `next build`：构建生产环境应用
67+
- `next start`：启动生产服务器
68+
- `next lint`：运行 ESLint
69+
70+
<AppOnly>
71+
72+
### 创建 `app` 目录
73+
74+
Next.js 使用文件系统路由，意味着应用路由由文件结构决定。
75+
76+
创建 `app` 文件夹，然后在其中创建 `layout.tsx` 文件作为[根布局](/docs/app/api-reference/file-conventions/layout#root-layouts)。该文件必须包含 `<html>` 和 `<body>` 标签。
77+
78+
```tsx filename="app/layout.tsx" switcher
79+
export default function RootLayout({
80+
children,
81+
}: {
82+
children: React.ReactNode
83+
}) {
84+
return (
85+
<html lang="en">
86+
<body>{children}</body>
87+
</html>
88+
)
89+
}
90+
```
91+
92+
```jsx filename="app/layout.js" switcher
93+
export default function RootLayout({ children }) {
94+
return (
95+
<html lang="en">
96+
<body>{children}</body>
97+
</html>
98+
)
99+
}
100+
```
101+
102+
创建首页内容 `app/page.tsx`：
103+
104+
```tsx filename="app/page.tsx" switcher
105+
export default function Page() {
106+
return <h1>Hello, Next.js!</h1>
107+
}
108+
```
109+
110+
```jsx filename="app/page.js" switcher
111+
export default function Page() {
112+
return <h1>Hello, Next.js!</h1>
113+
}
114+
```
115+
116+
当用户访问应用根路径 (`/`) 时，`layout.tsx` 和 `page.tsx` 会被渲染。
117+
118+
<Image
119+
alt="App 文件夹结构"
120+
srcLight="/docs/light/app-getting-started.png"
121+
srcDark="/docs/dark/app-getting-started.png"
122+
width="1600"
123+
height="363"
124+
/>
125+
126+
> **须知**：
127+
>
128+
> - 如果忘记创建根布局，运行 `next dev` 启动开发服务器时 Next.js 会自动创建该文件
129+
> - 可选择在项目根目录使用 [`src` 文件夹](/docs/app/api-reference/file-conventions/src-folder) 来分离应用代码和配置文件
130+
131+
</AppOnly>
132+
133+
<PagesOnly>
134+
135+
### 创建 `pages` 目录
136+
137+
Next.js 使用文件系统路由，意味着应用路由由文件结构决定。
138+
139+
在项目根目录创建 `pages` 文件夹，然后添加 `index.tsx` 文件作为首页 (`/`)：
140+
141+
```tsx filename="pages/index.tsx" switcher
142+
export default function Page() {
143+
return <h1>Hello, Next.js!</h1>
144+
}
145+
```
146+
147+
```jsx filename="pages/index.js" switcher
148+
export default function Page() {
149+
return <h1>Hello, Next.js!</h1>
150+
}
151+
```
152+
153+
接着在 `pages/` 中添加 `_app.tsx` 文件定义全局布局。了解更多关于[自定义 App 文件](/docs/pages/building-your-application/routing/custom-app)。
154+
155+
```tsx filename="pages/_app.tsx" switcher
156+
import type { AppProps } from 'next/app'
157+
158+
export default function App({ Component, pageProps }: AppProps) {
159+
return <Component {...pageProps} />
160+
}
161+
```
162+
163+
```jsx filename="pages/_app.js" switcher
164+
export default function App({ Component, pageProps }) {
165+
return <Component {...pageProps} />
166+
}
167+
```
168+
169+
最后在 `pages/` 中添加 `_document.tsx` 文件控制服务器初始响应。了解更多关于[自定义 Document 文件](/docs/pages/building-your-application/routing/custom-document)。
170+
171+
```tsx filename="pages/_document.tsx" switcher
172+
import { Html, Head, Main, NextScript } from 'next/document'
173+
174+
export default function Document() {
175+
return (
176+
<Html>
177+
<Head />
178+
<body>
179+
<Main />
180+
<NextScript />
181+
</body>
182+
</Html>
183+
)
184+
}
185+
```
186+
187+
```jsx filename="pages/_document.js" switcher
188+
import { Html, Head, Main, NextScript } from 'next/document'
189+
190+
export default function Document() {
191+
return (
192+
<Html>
193+
<Head />
194+
<body>
195+
<Main />
196+
<NextScript />
197+
</body>
198+
</Html>
199+
)
200+
}
201+
```
202+
203+
</PagesOnly>
204+
205+
### 创建 `public` 文件夹（可选）
206+
207+
在项目根目录创建 [`public` 文件夹](/docs/app/api-reference/file-conventions/public-folder) 存放图片、字体等静态资源。`public` 内的文件可通过根路径 (`/`) 引用。
208+
209+
例如 `public/profile.png` 可引用为 `/profile.png`：
210+
211+
```tsx filename="app/page.tsx" highlight={4} switcher
212+
import Image from 'next/image'
213+
214+
export default function Page() {
215+
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
216+
}
217+
```
218+
219+
```jsx filename="app/page.js" highlight={4} switcher
220+
import Image from 'next/image'
221+
222+
export default function Page() {
223+
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
224+
}
225+
```
226+
227+
## 运行开发服务器
228+
229+
1. 运行 `npm run dev` 启动开发服务器
230+
2. 访问 `http://localhost:3000` 查看应用
231+
3. 编辑<AppOnly>`app/page.tsx`</AppOnly> <PagesOnly>`pages/index.tsx`</PagesOnly> 文件并保存，浏览器中即可看到更新结果
232+
233+
## 配置 TypeScript
234+
235+
> 最低 TypeScript 版本要求：`v4.5.2`
236+
237+
Next.js 内置 TypeScript 支持。要添加 TypeScript 到项目，只需将文件重命名为 `.ts` / `.tsx` 并运行 `next dev`。Next.js 会自动安装必要依赖并添加包含推荐配置的 `tsconfig.json` 文件。
238+
239+
<AppOnly>
240+
241+
### IDE 插件
242+
243+
Next.js 包含自定义 TypeScript 插件和类型检查器，可供 VSCode 等代码编辑器实现高级类型检查和自动补全。
244+
245+
在 VS Code 中启用插件：
246+
247+
1. 打开命令面板 (`Ctrl/⌘` + `Shift` + `P`)
248+
2. 搜索 "TypeScript: Select TypeScript Version"
249+
3. 选择 "Use Workspace Version"
250+
251+
<Image
252+
alt="TypeScript 命令面板"
253+
srcLight="/docs/light/typescript-command-palette.png"
254+
srcDark="/docs/dark/typescript-command-palette.png"
255+
width="1600"
256+
height="637"
257+
/>
258+
259+
</AppOnly>
260+
261+
更多信息请参考 [TypeScript 参考文档](/docs/app/api-reference/config/next-config-js/typescript)。
262+
263+
## 配置 ESLint
264+
265+
Next.js 内置 ESLint 支持。使用 `create-next-app` 创建新项目时会自动安装必要包并配置正确设置。
266+
267+
要为现有项目手动添加 ESLint，在 `package.json` 中添加 `next lint` 脚本：
268+
269+
```json filename="package.json"
270+
{
271+
"scripts": {
272+
"lint": "next lint"
273+
}
274+
}
275+
```
276+
277+
然后运行 `npm run lint`，将引导完成安装和配置流程：
278+
279+
```bash filename="终端"
280+
npm run lint
281+
```
282+
283+
您会看到如下提示：
284+
285+
> ? 您希望如何配置 ESLint？
286+
>
287+
> ❯ 严格模式（推荐）
288+
> 基础模式
289+
> 取消
290+
291+
- **严格模式**：包含 Next.js 基础 ESLint 配置及更严格的 Core Web Vitals 规则集。初次设置 ESLint 时推荐此配置
292+
- **基础模式**：仅包含 Next.js 基础 ESLint 配置
293+
- **取消**：跳过配置。如计划自定义 ESLint 配置请选此项
294+
295+
选择"严格"或"基础"后，Next.js 会自动安装 `eslint` 和 `eslint-config-next` 依赖，并在项目根目录创建包含所选配置的 `.eslintrc.json` 文件。
296+
297+
现在可随时运行 `next lint` 执行 ESLint 检查。ESLint 设置完成后，每次构建 (`next build`) 时也会自动运行。错误会导致构建失败，而警告不会。
298+
299+
更多信息请参考 [ESLint 插件文档](/docs/app/api-reference/config/next-config-js/eslint)。
300+
301+
## 配置绝对导入和模块路径别名
302+
303+
Next.js 原生支持 `tsconfig.json` 和 `jsconfig.json` 文件中的 `"paths"` 和 `"baseUrl"` 选项。
304+
305+
这些选项允许将项目目录别名化为绝对路径，使模块导入更简洁。例如：
306+
307+
```jsx
308+
// 之前
309+
import { Button } from '../../../components/button'
310+
311+
// 之后
312+
import { Button } from '@/components/button'
313+
```
314+
315+
要配置绝对导入，在 `tsconfig.json` 或 `jsconfig.json` 中添加 `baseUrl` 配置选项。例如：
316+
317+
```json filename="tsconfig.json 或 jsconfig.json"
318+
{
319+
"compilerOptions": {
320+
"baseUrl": "src/"
321+
}
322+
}
323+
```
324+
325+
除配置 `baseUrl` 路径外，还可使用 `"paths"` 选项设置模块路径"别名"。
326+
327+
例如以下配置将 `@/components/*` 映射到 `components/*`：
328+
329+
```json filename="tsconfig.json 或 jsconfig.json"
330+
{
331+
"compilerOptions": {
332+
"baseUrl": "src/",
333+
"paths": {
334+
"@/styles/*": ["styles/*"],
335+
"@/components/*": ["components/*"]
336+
}
337+
}
338+
}
339+
```
340+
341+
每个 `"paths"` 都相对于 `baseUrl` 位置。

0 commit comments

Comments
 (0)