Nuxt4阶段一：环境搭建与第一个 Nuxt 4 项目
学习目标：安装开发环境、创建 Nuxt 4 项目、理解目录结构、跑通第一个页面。 预计时间：2–3 天 前置要求：会一点 HTML/CSS/JS；了解 Vue 3 Composition API 更佳（不了解也可边学边用）。
1. 为什么学 Nuxt 4？
Nuxt 是基于 Vue 3 的全栈 Web 框架。用它你可以：
- 用文件即路由的方式快速搭页面
- 默认支持 SSR（服务端渲染），对 SEO 友好
- 自动导入组件和 composables，少写样板代码
- 内置 Nitro 服务端引擎，直接写 API
- 一套代码可部署到 Node、Vercel、Cloudflare 等多种平台
Nuxt 4 相比 Nuxt 3 的重点升级：
| 默认 app/ 目录 | 应用代码更清晰，和 server 分离 |
| Singleton 数据层 | 相同 key 的请求自动共享，少重复请求 |
| TypeScript 项目分离 | app / server / shared 类型互不干扰 |
| 更快的 CLI | 开发启动更丝滑 |
官方文档：https://nuxt.com/docs/4.x 
2. 安装开发环境
2.1 安装 Node.js
Nuxt 4 需要 Node.js 20+（推荐 LTS）。
- 官网下载：https://nodejs.org/
- 或用 nvm / nvm-windows 管理多版本
验证：
node -v
# 应输出 v20.x 或更高，例如 v24.4.1
npm -v
2.2 安装 pnpm（推荐）
pnpm 更快、更省磁盘，Nuxt 生态也常用：
npm install -g pnpm
pnpm -v
也可以用 npm / yarn，本文统一用 pnpm。
2.3 编辑器建议
- Cursor 或 VS Code
- 推荐安装扩展：
- Vue – Official（Volar）
- TypeScript Vue Plugin (Volar)
- ESLint / Prettier（可选）
3. 创建第一个 Nuxt 4 项目
在你的学习目录下执行：
# 在空目录初始化（当前目录有内容时可用 –force，请先确认）
pnpm dlx nuxi@latest init .
# 或新建子目录
# pnpm dlx nuxi@latest init my-nuxt-app
# cd my-nuxt-app
交互提示时建议选择：
- Package manager：pnpm
- 是否立即安装依赖：Yes
- 是否初始化 Git：按需
安装完成后启动开发服务器：
pnpm install # 若未自动安装
pnpm dev
浏览器打开：http://localhost:3000
看到 Nuxt 欢迎页，说明环境 OK。
常用脚本：
| pnpm dev | 开发模式（热更新） |
| pnpm build | 生产构建 |
| pnpm preview | 本地预览生产构建 |
| pnpm generate | 生成静态站点（SSG） |
4. 认识 Nuxt 4 目录结构
初始化后，典型结构如下（Nuxt 4 默认使用 app/）：
your-project/
├── app/
│ ├── app.vue # 应用根组件
│ ├── pages/ # 页面 → 自动生成路由
│ ├── layouts/ # 布局模板
│ ├── components/ # 组件（自动导入）
│ ├── composables/ # 组合式函数（自动导入）
│ ├── middleware/ # 路由中间件
│ ├── plugins/ # 插件
│ ├── assets/ # 需构建处理的资源（css、图片等）
│ └── utils/ # 工具函数（自动导入）
├── server/
│ ├── api/ # API 路由 → /api/*
│ ├── middleware/ # 服务端中间件
│ └── utils/ # 仅服务端可用的工具
├── public/ # 原样拷贝的静态文件（favicon 等）
├── shared/ # 前后端共享代码（类型、常量）
├── nuxt.config.ts # Nuxt 配置入口
├── package.json
└── tsconfig.json
关键概念
| app/pages | 放页面，文件路径 = URL |
| app/layouts | 套在页面外的壳（导航、页脚） |
| app/components | 可复用 UI，写了就能用，不用 import |
| server/api | 后端接口，写文件就有 /api/xxx |
| nuxt.config.ts | 模块、样式、运行时配置都在这 |
5. 动手改第一个页面
5.1 看根组件 app/app.vue
Nuxt 默认大致是这样：
<template>
<div>
<NuxtRouteAnnouncer />
<NuxtWelcome />
</div>
</template>
要启用真正的页面路由，把它改成：
<template>
<NuxtLayout>
<NuxtPage />
</NuxtLayout>
</template>
说明：
- <NuxtLayout>：渲染当前布局
- <NuxtPage>：渲染 pages/ 里匹配到的页面
5.2 创建首页 app/pages/index.vue
<script setup lang="ts">
const title = '我的第一个 Nuxt 4 页面'
</script>
<template>
<main class="home">
<h1>{{ title }}</h1>
<p>你好，欢迎开始 Nuxt 4 学习之旅。</p>
<NuxtLink to="/about">去关于页 →</NuxtLink>
</main>
</template>
<style scoped>
.home {
max-width: 640px;
margin: 4rem auto;
padding: 0 1rem;
font-family: system-ui, sans-serif;
}
h1 {
font-size: 2rem;
}
a {
color: #00dc82;
}
</style>
5.3 创建关于页 app/pages/about.vue
<script setup lang="ts">
useSeoMeta({
title: '关于我',
description: '这是 Nuxt 4 学习计划阶段一的关于页',
})
</script>
<template>
<main class="about">
<h1>关于</h1>
<p>这是第二页。文件名 about.vue → 路由 /about。</p>
<NuxtLink to="/">← 返回首页</NuxtLink>
</main>
</template>
<style scoped>
.about {
max-width: 640px;
margin: 4rem auto;
padding: 0 1rem;
font-family: system-ui, sans-serif;
}
</style>
保存后刷新：
- http://localhost:3000/ → 首页
- http://localhost:3000/about → 关于页
这就是文件路由：路径由文件决定，不用手写路由表。
6. 配置文件初识 nuxt.config.ts
打开 nuxt.config.ts，先认识几个常用项：
// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
compatibilityDate: '2025-07-15',
// 开发工具
devtools: { enabled: true },
// 全局 CSS（路径相对项目根，或用 ~/assets）
// css: ['~/assets/css/main.css'],
// 运行时配置（密钥放服务端，公开配置放 public）
runtimeConfig: {
// 仅服务端可读
apiSecret: '',
public: {
// 客户端也能读
appName: 'Nuxt Tutorial',
},
},
})
读取公开配置（任意组件/页面里）：
const config = useRuntimeConfig()
console.log(config.public.appName)
环境变量约定：
- NUXT_API_SECRET → 映射到 runtimeConfig.apiSecret
- NUXT_PUBLIC_APP_NAME → 映射到 runtimeConfig.public.appName
7. 开发者工具
开发模式下，页面底部或浏览器扩展可打开 Nuxt DevTools：
- 查看路由、组件树
- 检查 useFetch / useAsyncData 状态
- 看 modules、hooks 等
启用方式（默认通常已开）：
export default defineNuxtConfig({
devtools: { enabled: true },
})
8. 本阶段小练习（必做）
按顺序完成，打勾：
加分题：
- 再建一页 /contact，表单有姓名、邮箱两个输入框（先不用提交）
- 给首页加一张放在 public/hero.jpg 的图片：<img src="/hero.jpg" alt="hero" />
9. 常见问题
Q：端口被占用？
pnpm dev — –port 3001
Q：改了代码没热更新？ 确认改的是 app/ 下文件；重启一次 pnpm dev。
Q：和 Nuxt 3 教程目录不一样？ Nuxt 4 默认把页面等放进 app/。老教程里根目录的 pages/，在 Nuxt 4 对应 app/pages/。
Q：必须用 TypeScript 吗？ 强烈建议用。也可以写纯 JS（.vue 里不写 lang="ts"），但后面类型提示会少很多。
10. 阶段总结
你已经完成：
- 开发环境与项目脚手架
- Nuxt 4 的 app/ 目录心智模型
- 文件路由与页面跳转
- 基础 SEO meta 与 runtimeConfig
下一篇：阶段二 —— 路由进阶、布局、组件自动导入、composables，做一个三页个人博客骨架。
参考链接
- Nuxt 4 Getting Started
- Installation
- Directory Structure
- Routing
