Nuxt 完整学习路径 - FunWay 文档

📌 关于 Nuxt： Nuxt 是一个基于 Vue 的全栈框架，支持服务端渲染（SSR）、静态站点生成（SSG）等多种渲染模式。最新版本 v4.4.2，GitHub 59.9K+ stars，每月 530 万次下载。

📋 学习路线图

环境准备（1-2 天）

Node.js 20.x+、VS Code + Vue 扩展、包管理器（npm/pnpm/bun）

基础入门（3-5 天）

项目创建、目录结构、路由系统、组件开发

核心概念（5-7 天）

自动导入、数据获取、状态管理、中间件

进阶实战（7-10 天）

服务端 API、认证系统、性能优化、部署上线

项目实战（10-15 天）

完整项目开发、最佳实践、测试与调试

🛠️ 第一步：环境准备

前置要求

Node.js - 20.x 或更新版本（推荐使用 LTS 版本）
文本编辑器 - VS Code + Vue 官方扩展或 WebStorm
终端 - 用于运行 Nuxt 命令
包管理器 - npm / yarn / pnpm / bun（任选其一）

💡 推荐配置： 使用 pnpm 作为包管理器，速度更快、磁盘占用更少。安装命令：npm install -g pnpm

📦 第二步：创建项目

1️⃣创建新项目

# 使用 npm
npm create nuxt@latest <project-name>

# 使用 pnpm
pnpm create nuxt@latest <project-name>

# 使用 bun
bunx create-nuxt@latest <project-name>

2️⃣进入项目目录

cd <project-name>

3️⃣安装依赖

# 使用 npm
npm install

# 使用 pnpm
pnpm install

4️⃣启动开发服务器

# 使用 npm
npm run dev

# 使用 pnpm
pnpm dev

# 自动打开浏览器
npm run dev -- -o

开发服务器将在 http://localhost:3000 启动

📁 第三步：理解目录结构

目录/文件	作用	说明
`app/`	应用核心目录	Nuxt 4 推荐结构
`app/components/`	组件目录	自动导入 Vue 组件
`app/composables/`	组合式函数	自动导入可复用逻辑
`app/utils/`	工具函数	自动导入辅助函数
`app/pages/`	页面路由	文件即路由
`server/`	服务端 API	Nitro 引擎驱动
`public/`	静态资源	直接复制到构建输出
`nuxt.config.ts`	配置文件	Nuxt 项目配置
`app.vue`	根组件	应用入口

⚡ 第四步：核心概念

1. 自动导入（Auto-imports）

Nuxt 自动导入组件、组合式函数、工具函数和 Vue API，无需手动 import：

app/app.vue

                    <script setup lang="ts">
// ref 和 computed 自动导入，无需 import
const count = ref(1)
const double = computed(() => count.value * 2)

// useFetch 自动导入
const { data, refresh, status } = await useFetch('/api/hello')
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double: {{ double }}</p>
  </div>
</template>
                

💡 提示： 如需显式导入，可以使用 import { ref, computed } from '#imports'

2. 文件路由系统

基于文件的路由，无需手动配置：

路由示例

app/pages/
├── index.vue          → /
├── about.vue          → /about
├── users/
│   ├── index.vue      → /users
│   └── [id].vue       → /users/:id (动态路由)
└── blog/
    ├── index.vue      → /blog
    └── [slug].vue     → /blog/:slug

3. 数据获取

Nuxt 提供强大的数据获取组合式函数：

app/pages/users/[id].vue

                    <script setup lang="ts">
const route = useRoute()
const userId = route.params.id

// useFetch - 服务端和客户端通用
const { data: user, pending, error } = await useFetch(`/api/users/${userId}`)

// useAsyncData - 更灵活的数据获取
const { data: posts } = await useAsyncData('posts', () => 
  $fetch('/api/posts')
)

// 刷新数据
const refreshUser = () => refresh()
</script>

<template>
  <div>
    <div v-if="pending">加载中...</div>
    <div v-else-if="error">错误：{{ error.message }}</div>
    <div v-else>
      <h1>{{ user.name }}</h1>
    </div>
  </div>
</template>
                

4. 状态管理

使用 useState 进行服务端渲染友好的状态管理：

app/composables/useCounter.ts

                    export const useCounter = () => {
  // useState 在服务端和客户端之间共享状态
  const count = useState('counter', () => 0)
  
  const increment = () => {
    count.value++
  }
  
  const decrement = () => {
    count.value--
  }
  
  return {
    count,
    increment,
    decrement
  }
}
                

5. 中间件（Middleware）

在页面渲染前执行逻辑，如权限验证：

app/middleware/auth.global.ts

                    export default defineNuxtRouteMiddleware((to, from) => {
  const { isAuthenticated } = useAuth()
  
  // 检查用户是否已认证
  if (!isAuthenticated.value && to.path !== '/login') {
    return navigateTo('/login')
  }
})
                

🎯 第五步：实战项目 - 博客系统

项目结构

my-nuxt-blog/
├── app/
│   ├── components/
│   │   ├── BlogCard.vue      # 博客卡片组件
│   │   ├── BlogList.vue      # 博客列表组件
│   │   └── NavBar.vue        # 导航栏
│   ├── composables/
│   │   └── useBlog.ts        # 博客数据获取
│   ├── pages/
│   │   ├── index.vue         # 首页
│   │   ├── blog/
│   │   │   ├── index.vue     # 博客列表页
│   │   │   └── [slug].vue    # 博客详情页
│   │   └── about.vue         # 关于页
│   └── app.vue               # 根组件
├── server/
│   └── api/
│       └── blog.ts           # 博客 API 路由
├── public/
│   └── images/               # 静态图片
└── nuxt.config.ts            # 配置文件

示例代码

app/composables/useBlog.ts

                    export const useBlog = () => {
  // 获取所有博客文章
  const fetchPosts = async () => {
    const { data } = await useFetch('/api/blog/posts')
    return data
  }
  
  // 获取单篇文章
  const fetchPostBySlug = async (slug: string) => {
    const { data } = await useFetch(`/api/blog/post/${slug}`)
    return data
  }
  
  return {
    fetchPosts,
    fetchPostBySlug
  }
}
                

app/pages/blog/index.vue

                    <script setup lang="ts">
const { fetchPosts } = useBlog()
const posts = await fetchPosts()
</script>

<template>
  <div class="blog-list">
    <h1>博客文章</h1>
    <BlogCard 
      v-for="post in posts" 
      :key="post.id"
      :post="post"
    />
  </div>
</template>

<style scoped>
.blog-list {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
}
</style>
                

server/api/blog/posts.ts

                    export default defineEventHandler(async (event) => {
  // 模拟博客数据
  const posts = [
    {
      id: 1,
      title: 'Nuxt 入门教程',
      slug: 'nuxt-getting-started',
      excerpt: '学习 Nuxt 的基础知识...',
      createdAt: '2026-03-01'
    },
    {
      id: 2,
      title: 'Vue 组合式 API 详解',
      slug: 'vue-composition-api',
      excerpt: '深入理解 Composition API...',
      createdAt: '2026-03-05'
    }
  ]
  
  return posts
})
                

🚀 第六步：构建与部署

生产构建

# 构建项目
npm run build

# 预览生产构建
npm run preview

部署选项

Vercel - 一键部署，自动检测 Nuxt
Netlify - 支持 SSR 和静态部署
Docker - 容器化部署
传统服务器 - Node.js 进程托管

💡 推荐： 使用 nuxi generate 生成静态站点，或使用 nuxi build 构建 SSR 应用。Nuxt 支持部署到任何平台！

📚 学习资源

官方文档 - nuxt.com/docs
GitHub 仓库 - 59.9K+ stars
Discord 社区 - 32K+ 成员在线交流
模板市场 - nuxt.com/templates
模块生态 - 200+ 官方和社区模块

✅ 学完本教程后，你将能够：

✅ 创建和配置 Nuxt 项目
✅ 理解并使用文件路由系统
✅ 掌握自动导入和数据获取
✅ 开发服务端 API 路由
✅ 实现状态管理和中间件
✅ 构建并部署生产应用

📖 原文链接

本文档内容整理自 Nuxt 官方文档：

📌 Nuxt - The Full-Stack Vue Framework
当前版本：v4.4.2 · GitHub Stars: 59.9K · 月下载：5.3M

← 返回文档中心

🚀 Nuxt 完整学习路径