Nuxt4 项目的约定配置都有哪些，哪些可以自动实现, 详细示例和使用说明

Nuxt 4 的核心哲学是"约定优于配置"，它通过预设的目录结构和命名规则，自动实现许多功能，让开发者无需编写繁琐的配置代码即可快速构建应用。

以下是 Nuxt 4 项目中主要的约定配置及其自动实现的功能详解。

📂 目录结构约定

Nuxt 4 采用了一套标准化的目录结构来组织代码。最显著的变化是，核心应用代码通常被组织在 app/ 目录下，这使得项目结构更加清晰。

app/: 包含大部分前端应用代码的核心目录。
- pages/: 自动路由 。在此目录下创建的 .vue 文件会根据其文件名和路径自动成为应用的路由。
- components/: 组件自动导入 。在此目录下的 Vue 组件可以被项目中任何其他地方直接使用，无需手动 import。
- composables/: 组合式函数自动导入。存放可复用的 Vue 组合式函数（类似 Hooks），同样支持自动导入。
- layouts/: 布局系统 。在此定义的布局组件（如 default.vue）可用于包装页面，实现统一的页眉、页脚等结构。
- plugins/: 插件自动注册。存放需要在应用根组件实例化前运行的插件（如第三方库），Nuxt 会自动加载它们。
- middleware/: 中间件系统。存放路由守卫逻辑，可以在页面渲染前执行特定代码（如权限校验）。
- assets/: 存放需要构建工具（如 Vite）处理的静态资源，如 SASS 文件、图片等。
server/: 存放服务端代码，由 Nitro 引擎驱动。
- api/: API 路由自动生成 。在此目录下创建的 *.ts 或 *.js 文件会自动成为服务端 API 端点。
- middleware/: 服务端中间件。
public/: 存放静态文件，如 favicon.ico、robots.txt。这些文件会直接映射到网站根目录，无需构建处理。
stores/: (约定) 存放 Pinia 状态管理文件。Nuxt 会为该目录下的 store 文件自动生成可自动导入的函数。
nuxt.config.ts: Nuxt 的主配置文件，用于配置模块、构建选项等。
app.config.ts: 用于定义在构建时确定、可暴露给客户端的应用级配置（如主题变量）。

⚡️ 自动实现的功能

基于上述目录约定，Nuxt 4 可以自动实现以下核心功能：

基于文件系统的路由 (File-system Routing)
- 约定 : 在 app/pages/ 目录下创建 .vue 文件。
- 自动实现 : Nuxt 会根据文件结构自动生成路由配置。
  - app/pages/about.vue → 路由 /about
  - app/pages/users/[id].vue → 动态路由 /users/:id
组件与组合式函数自动导入 (Auto-imports)
- 约定 : 将 Vue 组件放入 app/components/，将组合式函数放入 app/composables/。
- 自动实现 : 你可以在任何页面或组件中直接使用这些组件和函数，无需编写 import 语句。Nuxt 会在构建时自动处理导入和树摇（Tree-shaking）优化。
服务端渲染 (SSR) 与 API 路由
- 约定 : 框架默认开启 SSR。在 server/api/ 下创建文件。
- 自动实现 :
  - SSR: 页面在服务器端渲染成 HTML 后发送给浏览器，带来更快的首屏加载和更好的 SEO。
  - API 路由 : server/api/hello.ts 会自动创建一个 /api/hello 的 API 端点，让你可以轻松构建全栈应用。
零配置 TypeScript 支持
- 约定 : 使用 .ts 或 .vue 文件进行开发。
- 自动实现 : Nuxt 会自动生成 tsconfig.json 和相关类型定义文件，为你提供开箱即用的类型提示，无需手动配置 TypeScript。

💡 详细示例与使用说明

示例 1：创建页面和组件

创建页面 : 在 app/pages/index.vue 中编写首页代码。
创建组件 : 在 app/components/BaseButton.vue 中编写一个按钮组件。
使用 : 直接在 index.vue 中使用 <BaseButton>，无需 import。

vue 复制代码

<!-- app/pages/index.vue -->
<template>
  <div>
    <h1>欢迎来到首页</h1>
    <!-- 组件自动导入，直接使用 -->
    <BaseButton>点击我</BaseButton>
  </div>
</template>

示例 2：创建 API 接口

创建 API 文件 : 在 server/api/greeting.get.ts 中编写代码。
自动实现 : Nuxt 会自动创建一个 GET /api/greeting 接口。

typescript 复制代码

// server/api/greeting.get.ts
export default defineEventHandler(() => {
  return {
    message: 'Hello from Nuxt 4 API!'
  }
})

示例 3：配置 Pinia 状态管理

安装模块 : pnpm add @pinia/nuxt
配置 : 在 nuxt.config.ts 中添加模块。
创建 Store : 在 stores/counter.ts 中定义状态。
使用 : 在组件中直接使用 useCounterStore()，无需手动导入。

typescript 复制代码

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
})

typescript 复制代码

// stores/counter.ts
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    increment() { this.count++ }
  }
})

vue 复制代码

<!-- 在任何 .vue 文件中使用 -->
<script setup lang="ts">
// Store 自动导入，直接使用
const counter = useCounterStore()
</script>

示例 4：`nuxt.config.ts` vs `app.config.ts`

这两个配置文件职责不同，正确使用它们也是一种重要的约定。

特性	`nuxt.config.ts`	`app.config.ts`
主要用途	构建时和服务器端配置	公共的、应用级别的配置
环境变量	可通过环境变量覆盖 (`runtimeConfig`)	构建后无法被环境变量覆盖
客户端访问	仅 `runtimeConfig.public` 部分暴露	完全暴露给客户端
典型内容	模块、构建选项、私有 API 密钥	主题设置、网站标题、功能开关

Nuxt4 项目的约定配置都有哪些，哪些可以自动实现, 详细示例和使用说明

📂 目录结构约定

⚡️ 自动实现的功能

💡 详细示例与使用说明

示例 1：创建页面和组件

示例 2：创建 API 接口

示例 3：配置 Pinia 状态管理

示例 4：nuxt.config.ts vs app.config.ts

示例 4：`nuxt.config.ts` vs `app.config.ts`