编程马·菜鸟教程

Appearance

第3章：Nuxt 项目创建与目录解析 ​

1. 两种项目创建方式（新手推荐） ​

1.1 方式1：npx nuxi init 命令快速创建标准项目 ​

步骤：

  1. 打开终端：打开命令行终端（Windows 上的 PowerShell 或 CMD，Mac 上的 Terminal）

  2. 运行创建命令：

    bash
    # 使用 npm
npx nuxi init my-nuxt-app

# 使用 pnpm
pnpm dlx nuxi init my-nuxt-app

# 使用 yarn
yarn create nuxt-app my-nuxt-app

  3. 进入项目目录：

    bash
    cd my-nuxt-app

  4. 安装依赖：

    bash
    # 使用 npm
npm install

# 使用 pnpm
pnpm install

# 使用 yarn
yarn install

  5. 启动开发服务器：

    bash
    # 使用 npm
npm run dev

# 使用 pnpm
pnpm dev

# 使用 yarn
yarn dev

1.2 方式2：使用官方模板创建特定场景项目（如 SSR、静态站点） ​

Nuxt 提供了多种官方模板，可以根据不同的场景选择合适的模板。

步骤：

  1. 访问 Nuxt 模板库：访问 Nuxt Templates

  2. 选择模板：根据你的需求选择合适的模板，如：

    • Starter：基础模板
    • Content：内容管理模板
    • E-commerce：电商模板
    • Blog：博客模板

  3. 使用模板创建项目：

    bash
    # 例如，使用 Content 模板
npx nuxi init -t content my-content-app

  4. 安装依赖并启动：

    bash
    cd my-content-app
npm install
npm run dev

2. 项目依赖安装与启动（npm install、npm run dev 等命令） ​

2.1 安装依赖 ​

基本命令：

bash
# 安装所有依赖
npm install

# 安装特定依赖
npm install package-name

# 安装开发依赖
npm install --save-dev package-name

使用 pnpm：

bash
# 安装所有依赖
pnpm install

# 安装特定依赖
pnpm add package-name

# 安装开发依赖
pnpm add --save-dev package-name

使用 yarn：

bash
# 安装所有依赖
yarn install

# 安装特定依赖
yarn add package-name

# 安装开发依赖
yarn add --dev package-name

2.2 启动开发服务器 ​

基本命令：

bash
# 启动开发服务器
npm run dev

# 启动开发服务器并指定端口
npm run dev -- --port 3000

使用 pnpm：

bash
# 启动开发服务器
pnpm dev

# 启动开发服务器并指定端口
pnpm dev --port 3000

使用 yarn：

bash
# 启动开发服务器
yarn dev

# 启动开发服务器并指定端口
yarn dev --port 3000

2.3 构建生产版本 ​

基本命令：

bash
# 构建生产版本
npm run build

使用 pnpm：

bash
# 构建生产版本
pnpm build

使用 yarn：

bash
# 构建生产版本
yarn build

2.4 生成静态站点 ​

基本命令：

bash
# 生成静态站点
npm run generate

使用 pnpm：

bash
# 生成静态站点
pnpm generate

使用 yarn：

bash
# 生成静态站点
yarn generate

3. 项目目录结构逐文件解析（核心目录：pages、components、composables、public 等） ​

3.1 核心目录结构 ​

my-nuxt-app/
├── components/          # 组件目录
├── composables/         # 组合式函数目录
├── layouts/             # 布局目录
├── pages/               # 页面目录（自动生成路由）
├── public/              # 静态资源目录
├── server/              # 服务器目录
├── app.vue              # 应用入口组件
├── nuxt.config.ts       # Nuxt 配置文件
├── package.json         # 项目配置文件
└── tsconfig.json        # TypeScript 配置文件

3.2 核心目录详解 ​

3.2.1 components/ ​

  • 作用：存放 Vue 组件
  • 特性：组件会被自动导入，无需手动导入
  • 命名规范：组件名使用 PascalCase（如 Button.vue）
  • 示例：
    vue
    <!-- components/Button.vue -->
<template>
  <button class="btn">{{ text }}</button>
</template>

<script setup>
defineProps({
  text: String
})
</script>

3.2.2 composables/ ​

  • 作用：存放组合式函数（Composables）
  • 特性：Composables 会被自动导入，无需手动导入
  • 命名规范：文件名使用 camelCase（如 useCounter.ts）
  • 示例：
    typescript
    // composables/useCounter.ts
import { ref, computed } from 'vue'

export function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  const doubleCount = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  function decrement() {
    count.value--
  }

  return {
    count,
    doubleCount,
    increment,
    decrement
  }
}

3.2.3 layouts/ ​

  • 作用：存放布局组件
  • 特性：可以在页面中使用 layout 属性指定布局
  • 默认布局：default.vue 是默认布局
  • 示例：
    vue
    <!-- layouts/default.vue -->
<template>
  <div>
    <header>Header</header>
    <main>
      <slot />
    </main>
    <footer>Footer</footer>
  </div>
</template>

3.2.4 pages/ ​

  • 作用：存放页面组件，自动生成路由
  • 路由生成规则：
    • pages/index.vue → /
    • pages/about.vue → /about
    • pages/users/[id].vue → /users/:id
    • pages/users/[...slug].vue → /users/*
  • 示例：
    vue
    <!-- pages/index.vue -->
<template>
  <div>
    <h1>Home Page</h1>
    <p>Welcome to Nuxt.js</p>
  </div>
</template>

3.2.5 public/ ​

  • 作用：存放静态资源，如图片、字体、图标等
  • 访问方式：直接通过根路径访问，如 /images/logo.png
  • 示例：
    • public/images/logo.png → 访问路径：/images/logo.png
    • public/favicon.ico → 访问路径：/favicon.ico

3.2.6 server/ ​

  • 作用：存放服务器端代码，如 API 路由、中间件等
  • API 路由：在 server/api 目录下创建 API 路由
  • 示例：
    typescript
    // server/api/hello.ts
export default defineEventHandler((event) => {
  return {
    message: 'Hello from Nuxt API'
  }
})

3.2.7 app.vue ​

  • 作用：应用的入口组件
  • 特性：是整个应用的根组件
  • 示例：
    vue
    <!-- app.vue -->
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

4. 配置文件核心（nuxt.config.ts 基础配置与进阶配置） ​

4.1 基础配置 ​

nuxt.config.ts：

typescript
export default defineNuxtConfig({
  // 应用配置
  app: {
    head: {
      title: 'My Nuxt App',
      meta: [
        { name: 'description', content: 'A Nuxt.js application' }
      ],
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }
      ]
    }
  },

  // 构建配置
  build: {
    // 构建选项
  },

  // 模块
  modules: [
    // 模块列表
  ],

  // 运行时配置
  runtimeConfig: {
    // 运行时配置
  }
})

4.2 进阶配置 ​

nuxt.config.ts：

typescript
export default defineNuxtConfig({
  // 应用配置
  app: {
    baseURL: '/my-app/', // 应用的基础路径
    buildAssetsDir: '/assets/', // 构建资产目录
    pageTransition: {
      name: 'page',
      mode: 'out-in'
    } // 页面过渡效果
  },

  // 构建配置
  build: {
    transpile: ['some-package'], // 需要转译的包
    analyze: true, // 分析构建结果
    cssSourceMap: true // 启用 CSS 源映射
  },

  // 开发服务器配置
  devtools: {
    enabled: true // 启用开发工具
  },

  // 模块
  modules: [
    '@nuxt/content',
    '@nuxt/image',
    '@nuxtjs/color-mode'
  ],

  // 模块配置
  content: {
    // Content 模块配置
  },

  // 运行时配置
  runtimeConfig: {
    public: {
      apiBase: '/api' // 公共运行时配置
    },
    private: {
      apiKey: process.env.API_KEY // 私有运行时配置
    }
  },

  // CSS 配置
  css: [
    '@/assets/css/main.css'
  ],

  // 别名配置
  alias: {
    '@components': '@/components',
    '@composables': '@/composables'
  }
})

5. 自动导入机制（Nuxt 核心特性，无需手动导入组件/API） ​

5.1 组件自动导入 ​

特性：在 components 目录下的组件会被自动导入，无需手动导入。

使用方法：直接在模板中使用组件名。

示例：

vue
<template>
  <div>
    <Button text="Click me" />
  </div>
</template>

<script setup>
// 无需导入 Button 组件
</script>

5.2 Composables 自动导入 ​

特性：在 composables 目录下的组合式函数会被自动导入，无需手动导入。

使用方法：直接使用组合式函数名。

示例：

vue
<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double count: {{ doubleCount }}</p>
    <button @click="increment">Increment</button>
    <button @click="decrement">Decrement</button>
  </div>
</template>

<script setup>
// 无需导入 useCounter
const { count, doubleCount, increment, decrement } = useCounter()
</script>

5.3 API 自动导入 ​

特性：Nuxt 内置的 API 会被自动导入，无需手动导入。

常用 API：

  • useAsyncData：异步数据获取
  • useFetch：简化的数据获取
  • useRoute：获取路由信息
  • useRouter：路由导航
  • useHead：管理页面头部
  • useState：状态管理

示例：

vue
<template>
  <div>
    <h1>{{ title }}</h1>
    <p>{{ description }}</p>
  </div>
</template>

<script setup>
// 无需导入 useHead
useHead({
  title: 'My Page',
  meta: [
    { name: 'description', content: 'This is my page' }
  ]
})

// 无需导入 useRoute
const route = useRoute()
const title = computed(() => route.params.title || 'Default Title')
</script>

小结 ​

本章介绍了 Nuxt 项目的创建方式、目录结构和配置文件，以及 Nuxt 的自动导入机制。通过本章的学习，你应该已经掌握了如何创建和配置 Nuxt 项目，了解了 Nuxt 项目的目录结构和各个目录的作用，以及如何利用 Nuxt 的自动导入机制提高开发效率。

在接下来的章节中，我们将学习 Nuxt 的路由系统、页面与视图基础等核心特性，帮助你更深入地理解和使用 Nuxt.js。

© 2026 编程马·菜鸟教程 版权所有

基于 VitePress 构建