Nuxt4阶段一：环境搭建与第一个 Nuxt 4 项目

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. 本阶段小练习（必做）

按顺序完成，打勾：

1. Node 20+、pnpm 安装成功，pnpm dev 能打开页面
2. app.vue 使用 <NuxtLayout> + <NuxtPage>
3. 有首页 / 和关于页 /about，可用 <NuxtLink> 互相跳转
4. 在关于页用 useSeoMeta 设置了 title
5. 在 nuxt.config.ts 里加了 runtimeConfig.public.appName，并在首页展示它

加分题：

• 再建一页 /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