Nuxt.js 项目创建与核心结构详解

在现代 Web 开发中，选择合适的框架可以大幅提升开发效率。Nuxt.js 作为基于 Vue.js 的渐进式框架，凭借其开箱即用的服务端渲染（SSR）、静态站点生成（SSG）、自动路由管理等特性，成为构建高性能 Vue 应用的首选。

本文将详细介绍 Nuxt.js 项目的创建方式 和 核心目录结构，帮助开发者快速上手并深入理解其设计哲学。

1. Nuxt.js 项目创建

1.1 Nuxt 2 vs Nuxt 3

Nuxt.js 目前有两个主要版本：

• Nuxt 2（稳定版，基于 Vue 2）

• Nuxt 3（最新版，基于 Vue 3，支持 Composition API）

（1）Nuxt 2 项目创建

使用官方脚手架工具 create-nuxt-app：

npx create-nuxt-app my-project

运行后，CLI 会交互式询问配置选项，包括：

• UI 框架（如 Tailwind CSS、Bootstrap）

• 测试工具（Jest、Vitest）

• 渲染模式（SSR、静态站点、单页应用 SPA）

• 状态管理（Vuex）

（2）Nuxt 3 项目创建

Nuxt 3 采用新的 CLI 工具 nuxi，命令更简洁：

npx nuxi init my-project
cd my-project
npm install
npm run dev

Nuxt 3 默认支持：

• Vue 3 + Composition API

• Vite 构建工具（更快的热更新）

• 自动导入（无需手动引入组件和函数）

1.2 项目初始化后的关键操作

1. 安装依赖

   npm install
   # 或
   yarn install

2. 启动开发服务器

   npm run dev

   访问 http://localhost:3000 查看项目。

3. 生产环境构建

   npm run build  # 构建优化后的代码
   npm run start  # 启动生产服务器（SSR 模式）

4. 静态站点生成（SSG）

   npm run generate  # 生成静态 HTML 文件

2. Nuxt.js 项目结构解析

Nuxt.js 采用 约定优于配置（Convention Over Configuration） 的设计理念，通过特定的目录结构自动处理路由、布局和插件等逻辑。

2.1 通用目录结构（Nuxt 2 & 3）

my-project/
├── assets/          # 静态资源（SCSS、图片等，需构建）
├── components/      # Vue 组件（自动导入）
├── pages/           # 路由页面（自动生成路由）
├── public/          # 直接暴露的静态文件（如 favicon.ico）
├── nuxt.config.js   # Nuxt 配置文件（Nuxt 3 为 nuxt.config.ts）
└── package.json

（1）assets/

存放需要编译的静态资源，如：

• SCSS/SASS 文件

• 未优化的图片（Webpack/Vite 会处理）

（2）components/

所有 Vue 组件均可自动导入，无需手动 import。

（3）pages/

文件即路由：

• pages/index.vue → /

• pages/about.vue → /about

• pages/users/[id].vue → /users/1（动态路由）

（4）public/

直接复制到根目录，适合：

• robots.txt

• favicon.ico

• 无需构建的静态文件

（5）nuxt.config.js

核心配置文件，可定义：

• 模块（如 Tailwind CSS）

• 渲染模式（SSR/SSG/SPA）

• 全局 CSS 和插件

Nuxt 3 使用 TypeScript 配置：

export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss'],
  ssr: true,
})

2.2 Nuxt 3 特有结构

my-project/
├── app.vue          # 应用根组件（替代旧版 layouts/default.vue）
├── server/          # 服务端 API、中间件等
│   ├── api/         # API 路由（如 server/api/hello.ts）
│   └── middleware/  # 服务端中间件
├── composables/     # 自动导入的 Vue 组合式函数
├── utils/           # 工具函数（可选）
└── .nuxt/           # 构建生成的临时文件（勿手动修改）

（1）app.vue

Nuxt 3 的入口文件，替代了 layouts/default.vue：

<template>
  <NuxtLayout>  <!-- 布局系统 -->
    <NuxtPage /> <!-- 路由出口 -->
  </NuxtLayout>
</template>

（2）server/

用于服务端逻辑：

• server/api/hello.ts → 提供 /api/hello 接口

  export default defineEventHandler(() => {
    return { message: 'Hello Nuxt!' }
  })

• server/middleware/ → 服务端中间件（如身份验证）

（3）composables/

存放 Composition API 逻辑，自动全局导入：

// composables/useCounter.ts
export const useCounter = () => {
  const count = ref(0)
  const increment = () => count.value++
  return { count, increment }
}

在组件中直接使用：

<script setup>
const { count, increment } = useCounter()
</script>

2.3 Nuxt 2 特有结构

my-project/
├── layouts/         # 布局文件（如 default.vue）
├── middleware/      # 路由中间件（客户端）
├── store/           # Vuex 状态管理（自动启用）
└── plugins/         # 插件（如全局组件、第三方库）

（1）layouts/

定义页面布局：

<!-- layouts/default.vue -->
<template>
  <div>
    <Navbar />
    <slot /> <!-- 页面内容 -->
    <Footer />
  </div>
</template>

在页面中指定布局：

<script>
export default {
  layout: 'default'
}
</script>

（2）store/

使用 Vuex 管理状态：

// store/index.js
export const state = () => ({
  counter: 0
})

（3）plugins/

注册全局插件：

// plugins/vue-awesome.js
import Vue from 'vue'
import Icon from 'vue-awesome/components/Icon'

Vue.component('v-icon', Icon)

在 nuxt.config.js 中启用：

export default {
  plugins: ['~/plugins/vue-awesome']
}

3. 总结

Nuxt.js 通过合理的目录结构，让开发者专注于业务逻辑，而非繁琐的配置。

核心优势

✅ 自动路由：pages/ 目录生成路由
✅ SSR/SSG 支持：优化 SEO 和性能
✅ 模块化架构：轻松集成 Tailwind、Pinia 等
✅ TypeScript 友好（Nuxt 3）

无论是构建企业级 SSR 应用，还是静态博客，Nuxt.js 都能提供高效的开发体验。建议从 Nuxt 3 开始，享受 Vue 3 和 Vite 的最新特性！