Nuxt 3 基础入门教程

1. Nuxt 3 简介

Nuxt 3 是基于 Vue 3 构建的现代 Web 框架，旨在让 Web 开发直观且强大。

• 核心引擎: 基于 Nitro 引擎，支持跨平台部署（Node.js, Serverless, Workers）。
• 构建工具: 使用 Vite，开发体验极速。
• 特性: 自动导入、文件系统路由、服务端渲染 (SSR)、静态站点生成 (SSG)。

---

2. 环境搭建

确保 Node.js 版本 >= 18.0.0。

# 初始化项目
npx nuxi@latest init my-nuxt-app

# 进入目录
cd my-nuxt-app

# 安装依赖
npm install

# 启动开发服务器
npm run dev

浏览器访问 http://localhost:3000。

---

3. 目录结构与自动导入

Nuxt 3 最大的特点是约定优于配置。

• pages/: 页面目录，自动生成路由。
• components/: 组件目录，自动导入，无需手动 import。
• layouts/: 布局文件。
• public/: 静态资源 (如 /robot.txt, /favicon.ico)。
• server/: 后端 API 路由。
• app.vue: 应用的主入口组件。

---

4. 路由系统 (File-based Routing)

Nuxt 根据 pages/ 目录下的文件结构自动生成路由。

4.1 基础路由

创建 pages/index.vue:

<template>
  <div>
    <h1>首页</h1>
    <NuxtLink to="/about">跳转到关于页</NuxtLink>
  </div>
</template>

创建 pages/about.vue:

<template>
  <div>
    <h1>关于我们</h1>
    <NuxtLink to="/">返回首页</NuxtLink>
  </div>
</template>

4.2 动态路由

使用方括号 [] 创建动态路由。

创建 pages/posts/[id].vue:

<template>
  <div>
    <h1>文章 ID: {{ route.params.id }}</h1>
  </div>
</template>

<script setup>
const route = useRoute();
console.log(route.params.id);
</script>

访问 /posts/123 将显示 "文章 ID: 123"。

---

5. 组件自动导入

创建 components/AppHeader.vue:

<template>
  <header style="border-bottom: 1px solid #ccc; padding: 10px;">
    <strong>我的网站</strong>
  </header>
</template>

在 app.vue 或任何页面中直接使用，无需 import:

<template>
  <div>
    <AppHeader />
    <NuxtPage />
  </div>
</template>

---

6. 布局 (Layouts)

用于在多个页面间共享 UI（如导航栏、页脚）。

创建 layouts/default.vue:

<template>
  <div class="container">
    <nav>导航栏</nav>
    <!-- 页面内容插槽 -->
    <slot />
    <footer>页脚</footer>
  </div>
</template>

在 app.vue 中使用布局包裹页面：

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

---

7. 数据获取 (Data Fetching)

Nuxt 3 提供了 useFetch 和 useAsyncData 组合式函数，支持 SSR。

实战：获取用户列表

创建 pages/users.vue:

<template>
  <div>
    <h1>用户列表</h1>
    <div v-if="pending">加载中...</div>
    <div v-else-if="error">发生错误: {{ error.message }}</div>
    <ul v-else>
      <li v-for="user in users" :key="user.id">
        {{ user.name }} ({{ user.email }})
      </li>
    </ul>
  </div>
</template>

<script setup>
// useFetch 自动处理 SSR 和客户端水合
// 数据来源: JSONPlaceholder (公共测试 API)
const {
  data: users,
  pending,
  error,
} = await useFetch("https://jsonplaceholder.typicode.com/users");
</script>

---

8. 资源处理 (Assets)

• public/: 根目录下的文件会被原样服务。
  • 引用: <img src="/logo.png" />
• assets/: 需要构建工具处理的资源（如 CSS, SCSS, 字体）。
  • 引用: <img src="~/assets/image.png" />

全局 CSS 配置 (nuxt.config.ts):

export default defineNuxtConfig({
  css: ["~/assets/css/main.css"],
});

---

9. 总结实战：简单博客

1. app.vue: 设置布局入口。
2. pages/index.vue: 使用 useFetch 获取文章列表，循环展示 <NuxtLink :to="'/posts/'+post.id'">。
3. pages/posts/[id].vue: 根据 route.params.id 获取文章详情。

这是一个最基础的 Nuxt 3 应用结构，无需配置路由，无需手动导入组件，极大提升开发效率。

---