1.2 环境搭建与项目初始化

1.2 环境搭建与项目初始化

本节摘要：环境就绪是学习的起点。本节讲清 Node.js 版本要求、create-next-app 初始化项目的完整流程、项目目录结构（app/ 与 public/ 的作用），以及开发/构建/启动三条核心命令的用途。

本节目标

阅读完本节，你应当能够：

1. 准备满足要求的 Node.js 环境
2. 用 create-next-app 初始化项目并选择合适配置
3. 读懂 App Router 项目的目录结构
4. 使用 npm run dev/build/start 三条命令
5. 配置开发时的常用工具（TS、ESLint、Tailwind）

问题与直觉：为什么初始化如此重要

前端项目初始化是"第一次见面"——目录结构、构建工具、代码规范在这一步定型。Next.js 用 create-next-app 官方脚手架，把 TypeScript、ESLint、Tailwind 等"要不要、装什么"变成交互式选择，避免自己从零拼装。

直觉类比：create-next-app 像"精装房交付"——地基、水电、装修都按最佳实践配好，你拿到钥匙（项目）直接入住（写业务）。

💡 关键直觉：脚手架的价值不是"生成文件"，而是"锁定约定"。create-next-app 生成的目录结构就是 Next.js 的"约定"——app/ 放页面、public/ 放静态资源、next.config.js 做配置。理解了约定，任何 Next.js 项目你都能秒懂。

核心原理：环境要求与初始化

2.1 Node.js 版本要求

node --version     # 需要 18.17+（建议 20+）
npm --version      # 需要 9+
​

版本不足时，用 nvm（Node Version Manager）安装新版本：

nvm install 20
nvm use 20
​

2.2 create-next-app 初始化

npx create-next-app@latest my-app
​

交互式选项（按需选择）：

2.3 目录结构解读

my-app/
├── app/                    # App Router 根目录（页面都在这里）
│   ├── layout.tsx          # 根布局（全局框架）
│   ├── page.tsx            # 首页（/）
│   └── globals.css         # 全局样式
├── public/                 # 静态资源（图片、favicon）
├── next.config.js          # Next.js 配置
├── tsconfig.json           # TypeScript 配置
├── package.json            # 依赖与脚本
└── next-env.d.ts           # Next.js 类型声明
​

关键目录：

• app/：所有页面、布局、API 路由的所在地（文件即路由）；
• public/：直接通过 /xxx.png 访问的静态资源；
• next.config.js：图片域名、重定向、环境配置等。

工程实践要点：三条核心命令

3.1 开发模式

npm run dev
# 启动开发服务器，默认 http://localhost:3000
# 支持热更新（改代码自动刷新）
​

开发模式特性：错误提示直观（页面直接显示报错与堆栈）、热模块替换（HMR）、增量编译（只编译改动的部分）。

3.2 构建与启动

npm run build
# 生产构建：编译、预渲染、生成优化产物

npm run start
# 启动生产服务器（需先 build）
​

build 输出的关键信息：

Route (app)                    Size     First Load JS
┌ ○ /                          1.2 kB   89.3 kB
├ ƒ /posts/[id]                1.4 kB   90.1 kB
└ ○ /about                     900 B    88.7 kB

○  (Static)  静态预渲染（SSG）
ƒ  (Dynamic) 服务端渲染（SSR/动态）
​

看懂标记是第 1.1 节渲染模型的实操验证：○ 是构建时生成的静态页面，ƒ 是请求时才渲染的动态页面。

3.3 package.json 脚本一览

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}
​

常见误区与排查

动手演练：跑通第一个页面

# 1. 初始化（约 1-2 分钟）
npx create-next-app@latest my-app --typescript --tailwind --eslint --app

# 2. 进入目录并启动
cd my-app
npm run dev

# 3. 浏览器访问 http://localhost:3000
# 看到 Next.js 默认欢迎页即成功

# 4. 修改首页
# 编辑 app/page.tsx，把内容改成：
export default function Home() {
  return (
    <main>
      <h1>我的第一个 Next.js 页面</h1>
      <p>文件即路由——这个文件就是首页。</p>
    </main>
  );
}
​

保存后浏览器自动刷新，看到新内容——开发闭环已打通。

# 5. 查看构建标记（理解渲染模型）
npm run build
# 观察输出的 ○ / ƒ 标记
​

建议：把默认生成的 app/page.tsx 全部清空重写一遍，再添加 app/about/page.tsx 试试多页面——动手把"文件即路由"变成肌肉记忆。

核心回顾

• 环境要求：Node.js 18.17+（建议 20+），用 nvm 管理版本。
• 初始化：npx create-next-app@latest，推荐 TypeScript + ESLint + Tailwind + App Router。
• 目录结构：app/（页面与路由）、public/（静态资源）、next.config.js（配置）。
• 三条命令：dev（开发热更新）、build（生产构建）、start（生产启动）。
• 构建标记：○ 静态预渲染、ƒ 动态渲染——渲染模型的实操验证。
• 开发闭环：改代码 → 浏览器自动刷新 → 理解文件即路由。

深入理解：构建工具链在做什么

跑通 create-next-app 后，理解背后发生了什么，能帮你排查问题。

Next.js 的构建流程（npm run build 时）：

1. 收集路由：扫描 app/ 目录，生成路由清单；
2. 编译代码：TypeScript 转 JavaScript、JSX 转组件调用；
3. 预渲染静态页：能静态生成的页面在构建时渲染成 HTML（标 ○）；
4. 标记动态页：需要服务器渲染的页面标记为动态（标 ƒ）；
5. 代码分割：按路由拆分 JS chunk，首屏只加载需要的；
6. 生成产物：.next/ 目录存放编译结果与静态资源。

开发模式（dev）的区别：不做完整预渲染，而是按需编译——你访问哪个页面才编译哪个，配合热更新（改代码即时生效）。这就是为什么 dev 启动快、build 慢。

常见报错解读：

next.config.ts 的角色：它是"构建时配置"——图片域名白名单、重定向、实验特性都在这。配置改动后需要重启 dev 生效。

建议：把 npm run build 变成"提交前必跑"的习惯——build 通过 = 类型正确 + 路由无冲突 + 构建无错误，这是最便宜的"上线前体检"。

开发到部署的完整流程

开发用 dev 热更新，上线前 build 验证（类型、路由、预渲染），生产用 start 运行。

常见问题速答

问：create-next-app 每个选项都什么意思？
TypeScript（类型安全，建议开）、ESLint（代码规范）、Tailwind（样式方案）、src 目录（代码放 src/ 下）、App Router（本书主线）、导入别名（@/ 快捷路径）。不确定的选项保持默认即可。

问：dev 和 build 有什么区别？
dev 是开发模式：按需编译、热更新、错误提示直观；build 是生产构建：全量编译、预渲染、代码分割。上线必须 build + start。

问：改了代码不生效怎么办？
先确认是 dev 模式；改 next.config.ts 或环境变量需要重启；清 .next 目录后重启可解决大部分缓存问题。

问：npm 安装太慢/失败？
用国内镜像：`npm config set registry 「相关地址请参见官方文档」