项目初始化与约定

学习目标

学习工作台的第一块地基：一个可复现的 Next.js 工程。读完你应该能用 create-next-app 建好项目，读懂它生成的目录、配置、脚本和锁文件，并亲手验证开发模式与生产模式的区别。

问题场景

直接手搓一个 Next.js 项目要配置编译器、路由约定、TypeScript、ESLint……而 create-next-app 一条命令全配好。但很多人建完就只会 npm run dev，package.json 里每个脚本干什么、锁文件为什么必须提交，说不上来。

核心解释

建项目（TypeScript、App Router、不用 src 目录也行，本课用默认结构）：

npx create-next-app@latest reactlab-workspace --typescript --app --eslint
cd reactlab-workspace
npm run dev

打开后先做一次「盘点」，四个地方各有各的角色：

• app/：路由约定所在。app/page.tsx 是首页，app/layout.tsx 是根布局，app/globals.css 全局样式。App Router 的核心约定「目录即路由」就体现在这里；
• package.json：脚本清单。dev 是 next dev（开发服务器，文件一存热更新）；build 是 next build（把整个应用编译成生产产物）；start 是 next start（跑生产产物）。三个命令对应三种用途；
• next.config.ts：框架配置入口，暂时只有一个空配置，先知道它管什么即可；
• package-lock.json：依赖树的确切版本快照。提交进 git，任何人 npm ci 装出来的依赖都和你一字不差——这就是「可复现」的含义。

开发与生产的区别要亲手验证：

npm run build   # 输出各路由的产物类型（静态 ○ / 动态 ƒ）
npm run start   # 生产模式启动，默认 3000 端口

npm run dev 每次请求都现编译、报错带完整堆栈，方便调试但慢；next start 跑的是 build 时的固化产物，页面预渲染好、体积压缩过，这才是部署形态。生产模式还顺便帮你抓一类错误：有些写法开发时能跑、build 时直接报错。

示例拆解

按顺序完成的盘点清单：

• npm run dev 后访问 http://localhost:3000，看到默认首页；
• 打开 app/page.tsx 改一行文案并保存，浏览器立即热更新——这是开发模式;
• npm run build，观察终端输出：每条路由前面有标记（○ 静态预渲染、ƒ 动态渲染），记住首页默认是静态的；
• npm run start，再访问同一地址，确认内容一致、响应明显更快；
• 查看 .next/ 目录——build 产物都在这里，next start 依赖它，部署时不需要提交 git。

动手任务

在自己的机器上完成三件事：

1. 按 --typescript --app 创建项目，把 app/page.tsx 首页文案改成你的学习目标，热更新确认生效。
2. 分别跑 npm run build 和 npm run start，记录 build 输出里首页的路由标记（○ 还是 ƒ）。
3. 故意在 page.tsx 里写一个类型错误（比如把数字赋给字符串变量），对比 dev 模式和 build 模式各自的报错表现。

常见错误

• node_modules 和 .next 提交进 git：两者都能由 package.json + lockfile 重建；提交它们只会让仓库膨胀且冲突不断。
• 换机器或多人协作时用 npm install 装依赖：可能装出新版本；复现环境用 npm ci，严格按 lockfile 安装。
• 用 next start 之前忘了 next build：start 只会跑上次 build 的产物，没 build 过或改完没重新 build，跑的是旧代码。
• 把业务代码写进 next.config.ts：它是框架层配置（重定向、图片域名等），页面逻辑放 app/ 下。

检查与复盘

完成下方检查题确认理解。自查清单：

• 能说出 dev / build / start 三个脚本各自的作用和适用时机
• 知道 lockfile 的意义，会用 npm ci 复现依赖环境
• 盘点过 app、package.json、next.config.ts 三处，知道改动该落在哪

参考资料

• Next.js 文档：Installation —— create-next-app 参数与手动安装方式
• Next.js 文档：项目结构 —— app 目录与各类约定文件的官方地图
• Next.js 文档：next CLI —— dev/build/start 的命令行细节