Nuxt 3 快速上手：项目初始化与目录结构详解

实操指南

Nuxt 3 是基于 Vue 3、Vite 与 Nitro 构建的全栈通用框架，提供了开箱即用的约定式路由、组合式函数自动导入以及通用渲染（SSR）能力。本文将直接带你完成从环境检查到工程初始化的完整闭环操作，并深入剖析 Nuxt 3 独特的“按需约定”目录体系，帮助你建立清晰的工程架构认知。

一、开发环境要求与准备

在创建 Nuxt 3 项目之前，首先需要确认本地计算机的 Node.js 运行环境。Nuxt 3 深度依赖 ES Module 与现代底层构建链，对 Node.js 版本有明确要求：

• Node.js 版本：必须为 v18.20.0 以上版本，官方强烈推荐使用当前活跃的 v20.x LTS。如果使用旧版本（例如 16.x），启动时会因缺少 Node 原生 Web API（如 fetch、crypto）或 ESM 特性而报错中断。
• 包管理器：支持 pnpm、npm、yarn 或 bun。推荐优先使用 pnpm，它在解析符号链接与依赖去重方面与 Nuxt 3 的虚拟模块机制配合最为紧密。

打开终端执行以下命令，确认本地版本符合条件：

# 检查 Node.js 版本
node -v
# 输出示例：v20.12.0

# 检查包管理器版本
pnpm -v
# 输出示例：9.0.6

二、通过 Nuxi 初始化项目完整步骤

Nuxt 官方提供了名为 nuxi 的命令行工具。通过该工具可以一键拉取极简的初始模板，无须全局安装额外的脚手架依赖。

步骤 1：执行项目初始化命令

在目标工作目录下执行以下初始化命令，将 my-nuxt-app 替换为你自己的项目名称：

npx nuxi@latest init my-nuxt-app

在执行过程中，CLI 会通过交互式提示询问是否立即安装依赖以及选择哪一个包管理器（如 pnpm、npm 或 yarn）。你可以直接用键盘方向键选择 pnpm 并回车确认。

步骤 2：进入工程并安装依赖

如果刚才在交互提示中选择了跳过安装依赖，可以手动进入目录并执行安装：

cd my-nuxt-app
pnpm install

安装完成后，项目根目录会生成 node_modules/ 以及依赖锁文件 pnpm-lock.yaml。

步骤 3：启动本地开发服务器并验证

在工程根目录运行开发命令：

pnpm run dev

终端中将打印出本地监听地址与启动耗时，示例输出如下：

  Nuxt 3.12.0 with Nitro 2.9.6
  
  ➜ Local:    http://localhost:3000/
  ➜ Network:  use --host to expose

  ✔ Vite client built in 320ms
  ✔ Nitro built in 190ms

使用浏览器打开 http://localhost:3000，页面成功呈现绿白相间的 Nuxt 3 官方“Welcome”欢迎界面，这表明项目初始化已完全成功。

三、默认骨架与“按需约定”理念辨析

刚初始化完成的 Nuxt 3 项目目录非常干净。查看根目录，会发现默认仅有以下几个文件：

my-nuxt-app/
├── .gitignore
├── .nuxt/              # 运行后生成的临时运行时/类型目录
├── app.vue             # 应用主入口组件
├── nuxt.config.ts      # Nuxt 核心配置文件
├── package.json
└── tsconfig.json       # TypeScript 配置

常见困惑：“为什么没有看到 pages、components 目录？”

很多从 Nuxt 2 或其他框架转来的开发者会下意识认为脚手架缺失了文件。这实际上体现了 Nuxt 3 核心的按需约定（Convention over Configuration）设计思想：

• 最小化启动负载：Nuxt 3 默认是一个高性能的单页渲染骨架。如果不包含 pages/ 目录，框架不会加载 vue-router，从而避免打包多余的路由开销。
• 目录按需生效：只要你在根目录下新建了对应的约定目录（例如 pages/ 或 components/），Nuxt 编译器便会自动识别并无缝注入对应的路由系统或组件自动导入模块。不需要你在任何配置文件中手动注册。

四、标准工程目录全景与分层职责详解

随着业务需求的扩展，一个典型的中大型 Nuxt 3 项目会逐步扩充出清晰的分层目录。下图展示了各约定目录的分层职责体系：

下面按其承担的工程角色逐一说明各目录的具体用法与规范要求：

目录 / 文件	作用层级	核心约定与使用说明
app.vue	应用总入口	所有页面共享的最顶层挂载组件。如果启用了路由，必须在其中写入 <NuxtPage />。
pages/	约定式路由	目录下的 .vue 文件自动映射为浏览器访问路径，例如 pages/about.vue 对应 /about。
components/	UI 组件层	组件自动按需导入。支持子目录前缀命名规则，如 components/base/btn.vue 对应组件名 <BaseBtn />。
composables/	组合式逻辑	放置业务状态与自定义 Hooks，顶层导出的函数全项目自动按需导入，无需手写 import。
layouts/	布局模板	为页面提供通用框架布局（如 layouts/default.vue），配合 <NuxtLayout> 标签插槽使用。
server/	全栈服务端	Nitro 引擎驱动的后端服务目录，包含 server/api/、server/routes/ 与 server/middleware/。
public/	原生静态直通	原样保留并映射到网站根路径，不经过 Vite 构建（如 public/robots.txt 映射至 /robots.txt）。
assets/	构建静态资源	存放需要 Vite 编译处理的资源（SCSS、Less、图片、SVG、Web字体），在代码中以 ~/assets/ 引用。
plugins/	插件机制	Vue 插件或全局注入工具，文件名支持 .client.ts 或 .server.ts 进行运行端隔离。
middleware/	路由守卫	页面级与全局导航守卫，处理鉴权拦截、重定向或埋点逻辑。
nuxt.config.ts	全局配置	Nuxt 的唯一全局配置源，配置第三方模块、环境变量 runtimeConfig、SEO 元信息及 Vite 参数。

五、核心机制与关键规则深度辨析

1. app.vue 与 pages/ 的协作规则

初学者最容易踩的坑是在创建了 pages/index.vue 之后，访问浏览器却依然只能看到 app.vue 里的内容。

根本原因：app.vue 是全站组件树的根节点。一旦创建了 pages/ 目录，若要让路由页面显示出来，必须在 app.vue 中显式声明路由视图插槽 <NuxtPage />：

<!-- app.vue 正确写法 -->
<template>
  <div class="site-wrapper">
    <header>全站统一导航栏</header>
    <!-- 路由页面内容在此挂载渲染 -->
    <NuxtPage />
    <footer>全站统一页脚</footer>
  </div>
</template>

如果你的项目是纯多页面应用，且所有公共框架都在 layouts/ 中维护，你甚至可以直接把 app.vue 文件删除，Nuxt 会自动采用默认模板包裹 pages/。但在绝大多数实际项目中，保留 app.vue 作为全局状态容器与页面加载进度条（<NuxtLoadingIndicator />）的载体是更规范的做法。

2. 自动导入（Auto-imports）的运作与边界

Nuxt 3 提供了强大的自动导入机制。开发者可以在组件的 <script setup> 中直接使用 Vue 响应式 API（如 ref、computed）以及 composables/ 中定义的函数，而无须写任何 import 声明。

理解自动导入的边界十分重要：

• 顶层导出自动生效：composables/ 目录下的第一层文件所导出的变量与函数会被自动导入；若存在子文件夹（如 composables/user/info.ts），默认不会自动深层扫描，需要将其导出至 composables/index.ts，或者在 nuxt.config.ts 中显式开启深层路径扫描。
• 第三方 NPM 库不自动全局导入：除非该库是专门适配的 Nuxt 模块（并在 nuxt.config.ts 的 modules 中注册），普通的 npm 依赖（如 lodash-es、dayjs）在业务代码中使用时仍然需要常规 import。

3. public/ 与 assets/ 的区别

两者都用于存放静态资源，但底层处理机制截然不同：

• public/：放置不需要任何构建处理的文件，例如 favicon.ico、robots.txt、第三方离线 SDK 等。它在构建时会被原样拷贝到输出目录，代码中直接使用绝对根路径 /filename.ext 访问。
• assets/：放置需要由 Vite 进行编译、转译、压缩或添加哈希指纹的资源，例如 SCSS 样式表、全局 CSS、以及需要转成 Base64 或优化压缩的图片。代码中使用别名 ~/assets/styles/main.css 进行引用。

六、初始化就绪检查与项目构建决策

在完成初始化并规划好目录后，可以通过以下决策树与自检清单确认项目状态：

归纳而言，Nuxt 3 将项目初始化的复杂度降到了极低，并通过统一且直观的文件系统约定，让多端渲染、路由构建与接口开发有机结合在一起。在日常开发中，建议始终遵循“先按需添加目录，后渐进扩充功能”的原则，让工程保持轻量与易维护。