Skip to content

Update translations #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 2, 2025
Merged

Update translations #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 39 additions & 39 deletions apps/docs/content/zh-hans/docs/01-app/01-getting-started/01-installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,53 @@
---
source-updated-at: 2025-05-21T18:33:43.000Z
translation-updated-at: 2025-05-21T19:18:02.138Z
source-updated-at: 2025-06-01T01:32:20.000Z
translation-updated-at: 2025-06-01T22:11:51.399Z
title: 如何新建 Next.js 项目
nav_title: 安装指南
description: 使用 `create-next-app` CLI 创建新的 Next.js 应用，并配置 TypeScript、ESLint 和模块路径别名。
---

{/* 本文档内容在应用路由和页面路由间共享。如需添加仅适用于页面路由的内容，可使用 `<PagesOnly>内容</PagesOnly>` 组件。共享内容不应包裹在任何组件中。*/}
{/* 本文档内容在应用路由和页面路由间共享。如需添加仅适用于页面路由的内容，可使用 `<PagesOnly>内容</PagesOnly>` 组件。共享内容不应包裹在任何组件中。 */}

## 系统要求

开始前请确保系统满足以下要求：
开始前请确保您的系统满足以下要求：

- [Node.js 18.18](https://nodejs.org/) 或更高版本
- macOS、Windows（含 WSL）或 Linux 系统

## 自动安装

创建 Next.js 应用最快的方式是使用 [`create-next-app`](/docs/app/api-reference/cli/create-next-app)，它会自动完成所有配置。运行以下命令创建项目：
创建 Next.js 应用最快的方式是使用 [`create-next-app`](/docs/app/api-reference/cli/create-next-app)，它会自动为您完成所有设置。运行以下命令创建项目：

```bash filename="终端"
npx create-next-app@latest
```

安装过程中会看到以下提示：
安装过程中会显示以下提示：

```txt filename="终端"
请输入项目名称？my-app
是否使用 TypeScript？否 / 是
是否使用 ESLint？否 / 是
是否使用 Tailwind CSS？否 / 是
是否将代码放在 `src/` 目录下？否 / 是
是否使用应用路由（推荐）？否 / 是
是否使用 App Router？（推荐）否 / 是
是否在 `next dev` 中使用 Turbopack？否 / 是
是否自定义导入别名（默认为 `@/*`）？否 / 是
请输入配置的导入别名？@/*
```

完成提示后，[`create-next-app`](/docs/app/api-reference/cli/create-next-app) 会创建项目文件夹并安装所需依赖。
完成提示后，[`create-next-app`](/docs/app/api-reference/cli/create-next-app) 将创建以项目名命名的文件夹并安装所需依赖。

## 手动安装

要手动创建 Next.js 应用，请先安装必要包：
要手动创建 Next.js 应用，请先安装必要依赖包：

```bash filename="终端"
npm install next@latest react@latest react-dom@latest
```

然后在 `package.json` 中添加以下脚本：
然后在 `package.json` 文件中添加以下脚本：

```json filename="package.json"
{
Expand All @@ -71,9 +71,9 @@ npm install next@latest react@latest react-dom@latest

### 创建 `app` 目录

Next.js 使用文件系统路由，意味着应用路由由文件结构决定。
Next.js 使用文件系统路由，意味着应用中的路由由文件结构决定。

创建 `app` 文件夹，然后在其中创建 `layout.tsx` 文件作为[根布局](/docs/app/api-reference/file-conventions/layout#root-layouts)。该文件必须包含 `<html>` 和 `<body>` 标签。
创建 `app` 文件夹后，在其中添加 `layout.tsx` 文件作为[根布局](/docs/app/api-reference/file-conventions/layout#root-layout)。该文件必须包含 `<html>` 和 `<body>` 标签。

```tsx filename="app/layout.tsx" switcher
export default function RootLayout({
Expand Down Expand Up @@ -113,7 +113,7 @@ export default function Page() {
}
```

当用户访问应用根路径 (`/`) 时，`layout.tsx` 和 `page.tsx` 将同时渲染。
当用户访问应用根路径（`/`）时，`layout.tsx` 和 `page.tsx` 将同时被渲染。

<Image
alt="应用目录结构"
Expand All @@ -125,18 +125,18 @@ export default function Page() {

> **须知**：
>
> - 如果忘记创建根布局，运行 `next dev` 启动开发服务器时 Next.js 会自动生成
> - 可选择使用项目根目录下的 [`src` 文件夹](/docs/app/api-reference/file-conventions/src-folder) 来分离应用代码和配置文件
> - 如果忘记创建根布局，运行 `next dev` 启动开发服务器时 Next.js 会自动生成此文件
> - 可选择在项目根目录使用 [`src` 文件夹](/docs/app/api-reference/file-conventions/src-folder) 来分离应用代码与配置文件

</AppOnly>

<PagesOnly>

### 创建 `pages` 目录

Next.js 使用文件系统路由，意味着应用路由由文件结构决定。
Next.js 使用文件系统路由，意味着应用中的路由由文件结构决定。

在项目根目录创建 `pages` 文件夹，然后添加 `index.tsx` 作为首页 (`/`)：
在项目根目录创建 `pages` 文件夹，然后添加 `index.tsx` 文件作为首页（`/`）：

```tsx filename="pages/index.tsx" switcher
export default function Page() {
Expand All @@ -150,7 +150,7 @@ export default function Page() {
}
```

接着在 `pages/` 下添加 `_app.tsx` 定义全局布局。了解更多关于[自定义 App 文件](/docs/pages/building-your-application/routing/custom-app)。
接着在 `pages/` 下添加 `_app.tsx` 文件定义全局布局。了解更多关于[自定义 App 文件](/docs/pages/building-your-application/routing/custom-app)的信息。

```tsx filename="pages/_app.tsx" switcher
import type { AppProps } from 'next/app'
Expand All @@ -166,7 +166,7 @@ export default function App({ Component, pageProps }) {
}
```

最后在 `pages/` 下添加 `_document.tsx` 控制服务器初始响应。了解更多关于[自定义 Document 文件](/docs/pages/building-your-application/routing/custom-document)。
最后在 `pages/` 下添加 `_document.tsx` 文件控制服务器初始响应。了解更多关于[自定义 Document 文件](/docs/pages/building-your-application/routing/custom-document)的信息。

```tsx filename="pages/_document.tsx" switcher
import { Html, Head, Main, NextScript } from 'next/document'
Expand Down Expand Up @@ -204,7 +204,7 @@ export default function Document() {

### 创建 `public` 文件夹（可选）

在项目根目录创建 [`public` 文件夹](/docs/app/api-reference/file-conventions/public-folder) 存放静态资源（如图片、字体等）。`public` 中的文件可通过根路径 (`/`) 引用。
在项目根目录创建 [`public` 文件夹](/docs/app/api-reference/file-conventions/public-folder) 存放静态资源如图片、字体等。`public` 中的文件可通过根路径（`/`）引用。

例如 `public/profile.png` 可引用为 `/profile.png`：

Expand All @@ -228,23 +228,23 @@ export default function Page() {

1. 执行 `npm run dev` 启动开发服务器
2. 访问 `http://localhost:3000` 查看应用
3. 编辑 <AppOnly>`app/page.tsx`</AppOnly><PagesOnly>`pages/index.tsx`</PagesOnly> 文件并保存，浏览器中即可看到更新结果
3. 编辑 <AppOnly>`app/page.tsx`</AppOnly><PagesOnly>`pages/index.tsx`</PagesOnly> 文件并保存，浏览器中将实时更新

## 配置 TypeScript

> TypeScript 最低版本要求：`v4.5.2`
> 最低 TypeScript 版本要求：`v4.5.2`

Next.js 内置 TypeScript 支持。要将 TypeScript 添加到项目，只需将文件重命名为 `.ts`/`.tsx` 并运行 `next dev`。Next.js 会自动安装必要依赖并创建包含推荐配置的 `tsconfig.json` 文件。
Next.js 内置 TypeScript 支持。要将 TypeScript 添加到项目，只需将文件重命名为 `.ts` / `.tsx` 并运行 `next dev`。Next.js 会自动安装必要依赖并生成包含推荐配置的 `tsconfig.json` 文件。

<AppOnly>

### IDE 插件

Next.js 包含自定义 TypeScript 插件和类型检查器，可供 VSCode 等编辑器实现高级类型检查和自动补全。
Next.js 包含自定义 TypeScript 插件和类型检查器，可供 VSCode 等代码编辑器实现高级类型检查和自动补全。

在 VS Code 中启用插件：

1. 打开命令面板 (`Ctrl/⌘` + `Shift` + `P`)
1. 打开命令面板（`Ctrl/⌘` + `Shift` + `P`）
2. 搜索 "TypeScript: 选择 TypeScript 版本"
3. 选择 "使用工作区版本"

Expand All @@ -258,13 +258,13 @@ Next.js 包含自定义 TypeScript 插件和类型检查器，可供 VSCode 等

</AppOnly>

更多信息请参考 [TypeScript 配置文档](/docs/app/api-reference/config/next-config-js/typescript)。
更多信息请参考 [TypeScript 参考文档](/docs/app/api-reference/config/next-config-js/typescript)。

## 配置 ESLint

Next.js 内置 ESLint 支持。使用 `create-next-app` 创建项目时会自动安装必要包并配置正确设置。
Next.js 内置 ESLint 支持。使用 `create-next-app` 创建新项目时会自动安装必要包并配置正确设置。

要为现有项目手动添加 ESLint，请在 `package.json` 中添加 `next lint` 脚本：
要为现有项目手动添加 ESLint，在 `package.json` 中添加 `next lint` 脚本：

```json filename="package.json"
{
Expand All @@ -274,35 +274,35 @@ Next.js 内置 ESLint 支持。使用 `create-next-app` 创建项目时会自动
}
```

然后运行 `npm run lint`，安装向导将引导完成配置过程：
然后运行 `npm run lint`，系统将引导您完成安装和配置流程：

```bash filename="终端"
npm run lint
```

您将看到如下提示：

> ? 希望如何配置 ESLint？
> ? 您希望如何配置 ESLint？
>
> ❯ 严格模式（推荐）
> 基础模式
> 取消

- **严格模式**：包含 Next.js 基础 ESLint 配置及更严格的 Core Web Vitals 规则集。首次配置 ESLint 时推荐使用
- **严格模式**：包含 Next.js 基础 ESLint 配置及更严格的 Core Web Vitals 规则集。首次设置 ESLint 时推荐此配置
- **基础模式**：仅包含 Next.js 基础 ESLint 配置
- **取消**：跳过配置。如需自定义 ESLint 配置请选择此项
- **取消**：跳过配置。如需自定义 ESLint 配置可选择此项

选择"严格"或"基础"后，Next.js 会自动安装 `eslint` 和 `eslint-config-next` 依赖，并在项目根目录创建包含所选配置的 `.eslintrc.json` 文件。
选择"严格"或"基础"模式后，Next.js 会自动安装 `eslint` 和 `eslint-config-next` 依赖，并在项目根目录创建包含所选配置的 `.eslintrc.json` 文件。

此后可通过运行 `next lint` 执行 ESLint 检查。ESLint 配置完成后，每次构建 (`next build`) 时也会自动运行。错误会导致构建失败，而警告不会。
此后可随时运行 `next lint` 进行错误检查。ESLint 设置完成后，每次构建（`next build`）时也会自动运行。错误会导致构建失败，而警告则不会。

更多信息请参考 [ESLint 插件文档](/docs/app/api-reference/config/next-config-js/eslint)。

## 配置绝对导入和模块路径别名

Next.js 原生支持 `tsconfig.json` 和 `jsconfig.json` 中的 `"paths"` 和 `"baseUrl"` 选项。
Next.js 原生支持 `tsconfig.json` 和 `jsconfig.json` 文件中的 `"paths"` 和 `"baseUrl"` 选项。

这些选项允许将项目目录映射为绝对路径，使模块导入更清晰简洁。例如：
这些选项允许您将项目目录映射为绝对路径，使模块导入更简洁清晰。例如：

```jsx
// 之前
Expand All @@ -312,7 +312,7 @@ import { Button } from '../../../components/button'
import { Button } from '@/components/button'
```

要配置绝对导入，请在 `tsconfig.json` 或 `jsconfig.json` 中添加 `baseUrl` 配置：
要配置绝对导入，在 `tsconfig.json` 或 `jsconfig.json` 中添加 `baseUrl` 配置选项。例如：

```json filename="tsconfig.json 或 jsconfig.json"
{
Expand All @@ -322,7 +322,7 @@ import { Button } from '@/components/button'
}
```

除配置 `baseUrl` 外，还可使用 `"paths"` 选项设置模块路径"别名"。
除配置 `baseUrl` 路径外，还可使用 `"paths"` 选项设置模块路径"别名"。

例如以下配置将 `@/components/*` 映射到 `components/*`：

Expand All @@ -338,4 +338,4 @@ import { Button } from '@/components/button'
}
```

每个 `"paths"` 都相对于 `baseUrl` 指定的位置。
每个 `"paths"` 都相对于 `baseUrl` 位置进行解析。
Loading