Next.js 项目安装与初始化完全指南
2025-07-05 01:03:46作者：裴麒琰
前言
Next.js 作为 React 的元框架，提供了开箱即用的 SSR、SSG 等能力，极大简化了现代 Web 应用的开发流程。本文将详细介绍如何从零开始安装和初始化一个 Next.js 项目，涵盖自动化和手动两种方式，以及相关工具的配置。
系统要求
在开始之前，请确保您的开发环境满足以下最低要求：
- Node.js 18.18 或更高版本
- 支持的操作系统：macOS、Windows（包括 WSL）或 Linux
自动安装（推荐）
对于大多数开发者，使用官方提供的脚手架工具是最快捷的方式：
npx create-next-app@latest
执行命令后，系统会交互式地询问以下配置选项：
- 项目名称
- 是否使用 TypeScript
- 是否集成 ESLint
- 是否使用 Tailwind CSS
- 是否将代码放在 src 目录下
- 是否使用 App Router（推荐）
- 是否启用 Turbopack 作为开发服务器
- 是否自定义模块别名（默认 @/*）
脚手架会自动完成以下工作：
- 创建项目目录结构
- 安装所有依赖项
- 配置基础开发脚本
- 根据选择集成相关工具
手动安装（高级）
对于需要更精细控制的开发者，可以手动初始化项目：
- 首先安装核心依赖：
npm i next@latest react@latest react-dom@latest
- 然后在 package.json 中添加必要的脚本：
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
}
}
项目结构配置
根据使用的路由模式（App Router 或 Pages Router），需要创建不同的目录结构：
App Router 模式（推荐）
- 创建 app 目录
- 添加根布局文件 app/layout.tsx：
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
- 创建首页 app/page.tsx：
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
Pages Router 模式
- 创建 pages 目录
- 添加首页 pages/index.tsx
- 创建全局布局 pages/_app.tsx
- 添加文档模板 pages/_document.tsx
静态资源管理
创建 public 目录用于存放静态资源（图片、字体等），这些资源可以通过根路径直接访问：
import Image from 'next/image'
export default function Page() {
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}
开发服务器
执行以下命令启动开发服务器：
npm run dev
访问 http://localhost:3000 即可查看应用，修改代码后会自动热更新。
进阶配置
TypeScript 集成
Next.js 内置 TypeScript 支持，只需将文件扩展名改为 .ts/.tsx 并启动开发服务器，系统会自动：
- 安装 @types 依赖
- 生成推荐的 tsconfig.json
- 启用类型检查
对于 VSCode 用户，建议启用工作区 TypeScript 版本以获得最佳开发体验。
ESLint 配置
Next.js 提供了开箱即用的 ESLint 支持，提供两种预设配置：
- 严格模式（推荐）：包含核心 Web Vitals 相关规则
- 基础模式：仅包含基本规则
通过 package.json 中的 lint 脚本即可运行检查：
npm run lint
模块别名
通过配置 tsconfig.json/jsconfig.json 可以简化模块导入路径：
{
"compilerOptions": {
"baseUrl": "src/",
"paths": {
"@/components/*": ["components/*"],
"@/styles/*": ["styles/*"]
}
}
}
配置后可以使用更简洁的导入方式：
import Button from '@/components/button'
结语
本文详细介绍了 Next.js 项目的初始化流程，从最简单的脚手架方式到手动配置的各个环节。无论您是初学者还是经验丰富的开发者，都能找到适合自己的项目初始化方式。建议新项目优先采用 App Router 模式，它能提供更现代化的开发体验和更好的性能优化。
