手帐 Blog

主题

02 · 安装工具链与第一个 App Router 应用 ​

目标：本机用官方路径创建 Next.js App Router + TypeScript 应用，改首页看到变化。
官方主文：Installation · Project Structure

1. 前置检查 ​

bash
node -v
pnpm -v
  • Node：建议 20.9+（以 Next 官方 Installation 页当前要求为准；版本不够先升级）。
  • 包管理：本系列示例用 pnpm（与 Journal monorepo 习惯一致）；npm / yarn 亦可，照官方命令替换即可。

AI 注意：若 AI 让你 create-react-app 或只建 Vite SPA——本系列收束是 Next App Router，以 nextjs.org 为准。

2. 创建项目（只走官方） ​

在任意学习目录（不必塞进 Journal monorepo）：

bash
pnpm create next-app@latest notes-board-lab

交互选项建议（与官方默认接近即可）：

选项建议
TypeScriptYes
ESLintYes
TailwindYes（省事；也可用 No）
src/ 目录随意；下文以默认 app/ 在根为例
App RouterYes（必须）
Turbopack按官方提示选
自定义 import alias@/* 即可

进入目录并启动：

bash
cd notes-board-lab
pnpm dev

浏览器打开终端提示的本地地址（通常 http://localhost:3000），应看到模板首页。

3. 认路：App Router 最小结构 ​

对照 Project Structure：

text
notes-board-lab/
  app/
    layout.tsx    # 根布局（共享壳）
    page.tsx      # 路由 `/` 的页面
    globals.css
  package.json
  next.config.ts  # 或 .mjs / .js
  tsconfig.json
文件角色（Vue 对照）
app/layout.tsx接近「根 layout / App.vue 壳」
app/page.tsx接近「首页路由组件」
app/globals.css全局样式入口

先不要新建 pages/ 目录——那是 Pages Router，本系列不走。

4. 第一次手敲：改首页 ​

打开 app/page.tsx，删掉模板营销内容，改成类似：

tsx
export default function HomePage() {
  return (
    <main style={{ padding: 24 }}>
      <h1>Notes Board Lab</h1>
      <p>我的第一个 App Router 页面。</p>
    </main>
  )
}

保存后热更新应立刻反映。若没有：确认 pnpm dev 仍在跑、改的是 app/page.tsx 而非别的副本。

再打开 app/layout.tsx，改 metadata.title（或 <title> 相关配置）为 Notes Board Lab，刷新看浏览器标签。

5. 编辑器（AI 时代也要语言服务） ​

  • Cursor / VS Code：装好 TypeScript、ESLint；打开项目根让 TS server 认到 tsconfig.json。
  • 确认 JSX 报错能点进类型定义（说明不是「纯文本瞎补全」）。

没有语言服务，AI 更容易发明不存在的 Next API。

6. 必做验收 ​

  • [ ] node -v / pnpm -v 可用
  • [ ] pnpm create next-app@latest 成功且选了 App Router
  • [ ] pnpm dev 能打开本地页
  • [ ] 改过 page.tsx 与 layout metadata，肉眼可见
  • [ ] 能向别人指认：app/、layout.tsx、page.tsx 各是什么

7. AI 提示词约束（本篇） ​

text
技术约束：
- Next.js App Router + TypeScript
- 禁止 Pages Router、禁止 create-react-app
- 不要额外安装 UI 库 / 状态库

任务：解释我当前 app/layout.tsx 与 app/page.tsx 的职责，
并引用 nextjs.org/docs 对应章节标题。

8. 下一步 ​

→ 03 · Learn React 补手感：组件 / props / state

官方入口 ​