Nuxt 4 项目目录结构全解析：app、public、server 目录作用与约定

本节目标：弄懂 Nuxt 4 每类目录各自负责什么，特别记住 app/ 这个代码主目录，以及 public/、server/、nuxt.config.ts 各自的角色。

Nuxt 最大的省心之处，就是「目录即约定」：你把文件放在特定文件夹，框架就自动知道它是什么、该怎么用。所以读懂目录结构，等于读懂了 Nuxt 一半的工作方式。本章以 Nuxt 4 的约定为准。

4-1

一个 Nuxt 4 项目，根目录下最重要的几个文件是：

nuxt.config.ts：项目总配置。所有全局开关（渲染模式、模块、运行时配置等）都在这里。后面第 7 章专门讲。
package.json：记录依赖和脚本（dev/build/generate 等命令）。
tsconfig.json：TypeScript 配置，由 Nuxt 自动生成，不要手动改，要改通过 nuxt.config.ts（详见第 9 章）。
.nuxt/：构建时自动生成的类型与临时文件，你一般不用碰它。
.output/：执行 nuxt build 后产出的部署目录。

Warning

tsconfig.json 和 .nuxt/ 都是 Nuxt 自动维护的，手动改动很可能被下一次构建覆盖。要调整类型或构建行为，请走 nuxt.config.ts 里的对应字段。

4-2

Nuxt 4 把绝大多数「源码」收进 app/ 目录（它的技术名叫 srcDir）。这是 Nuxt 4 与老版本最直观的区别。里面常见的子目录：

子目录	作用
`app/app.vue`	应用根组件，所有页面的挂载点
`app/pages/`	页面文件，自动生成路由
`app/components/`	Vue 组件，自动导入
`app/composables/`	组合式函数，自动导入
`app/layouts/`	页面外层布局
`app/middleware/`	路由中间件（导航前执行）
`app/plugins/`	应用启动时运行的插件
`app/utils/`	通用工具函数
`app/assets/`	需要被构建工具处理的资源（如 Sass）
`app/app.config.ts`	构建期确定的公开配置
`app/error.vue`	自定义错误页

你不需要一开始就把这些目录全建出来。Nuxt 是「用到了才建」——比如你不写 pages/，路由功能就不启用；不写 components/，组件自动导入也就没有可导入的东西。

Tip

习惯 Nuxt 3 的读者注意：Nuxt 3 里 components/、pages/ 等是平铺在项目根下的。Nuxt 4 把它们整体搬进了 app/。如果你从老项目迁移，需要把源码移动进 app/ 并在配置里确认 compatibilityVersion（见下文）。

4-3

public/ 放「原样不动」的静态文件：图标 favicon.ico、爬虫规则 robots.txt、不会变动的图片等。构建时这些文件会直接复制到产物根目录，不经过任何处理，文件名也保持不变。

在 Nuxt 4 中，public/ 位于 app/public/（即 app/ 之内）。引用时直接写根路径即可：

<template>
  <!-- 引用 public 里的 logo.svg，路径从根开始 -->
  <img src="/logo.svg" alt="站点 logo" />
</template>

Note

public/ 与 assets/ 容易混：public/ 是「原样拷贝、名字不变」，assets/ 是「交给构建工具处理（压缩、哈希命名）」。需要保持固定文件名的用 public/，需要被打包优化的用 assets/。第 29–30 章会展开讲。

4-4

Nuxt 之所以是「全栈」框架，靠的就是 server/。在这里写的代码运行在服务端（Node 环境），不会被打包进浏览器。常见子目录：

server/api/：后端接口，访问 /api/xxx 就能调用。
server/routes/：更灵活的服务端路由（如动态生成 sitemap.xml）。
server/middleware/：每个请求到达前先执行的中间件。
server/utils/：服务端专用工具函数。

Nitro 引擎会扫描这些文件，自动把 server/api/ 下的文件变成可用的 HTTP 接口。也就是说，写一个后端接口不需要单独起一个 Express 服务——直接在 server/api/ 里建文件就行。

4-5

nuxt.config.ts 是项目配置的「单一事实来源」。Nuxt 4 项目里通常会看到一行：

export default defineNuxtConfig({
  compatibilityVersion: 4,
})

compatibilityVersion 告诉 Nuxt「按哪个大版本的约定来工作」。设为 4 时，目录约定、srcDir 默认值等都采用 Nuxt 4 行为（即 app/ 主目录）。老项目如果还是 3，框架会按 Nuxt 3 的旧约定（根目录平铺）来解析。

Note

新创建的 Nuxt 4 项目默认就是 compatibilityVersion: 4，你通常不用手动写。只有当老项目想逐步迁移、或你想在 Nuxt 4 里临时回退某些旧行为时，才需要动这个字段。Nuxt 2 已停止维护，本教程不覆盖。

4-6

随着项目变大，你可能还会用到：

shared/：前端（app/）和服务端（server/）都能引用的共享代码。
modules/：项目本地的 Nuxt 模块。
layers/：可复用的代码层（配置、组件、组合式函数打包成一层供多个项目共享）。
content/：安装 @nuxt/content 模块后用于存放 Markdown 内容。
test/：放测试代码（单元、端到端）。

4-7

你可能会想：为什么非要把页面放 pages/、组件放 components/？因为 Nuxt 的「约定优于配置」就是靠这套目录起作用的。

在传统前端项目里，每用一个组件都要手动 import；每加一个页面都要去路由文件里登记。Nuxt 把这类重复劳动自动化了：pages/ 里的文件自动变成路由，components/ 里的组件自动能被任何地方引用，composables/ 里的函数也一样。你只管按约定放文件，框架帮你接好线。

Tip

这套自动导入是「按目录识别」的，不是按文件名。所以只要你把文件放进正确的目录，哪怕文件名随便起，Nuxt 也能识别并自动导入。

代价是：你得记住每个目录的「特殊含义」。这章前面列的那些子目录，其实就是 Nuxt 给你预设好的一套插槽——你往里插文件，它就帮你通电。前期记目录有点烦，习惯后写代码会快很多。

还有一点容易忽略：app/ 收拢源码后，项目根目录只剩下配置和少量目录，干净不少。当你以后想找「某段逻辑到底在哪」，顺着目录约定去猜，命中率很高——这也是约定带来的隐性好处。

4-8

记住四块就够入门：app/ 装所有前端源码、public/（app/public）放原样静态文件、server/ 写后端、nuxt.config.ts 管全局配置。compatibilityVersion: 4 是 Nuxt 4 行为的开关。下一章我们启动开发服务器，看这些文件怎么实时跑起来。

4-7 目录约定背后的设计哲学

Nuxt 的目录约定并不是随意制定的，它遵循了”约定优于配置”的核心思想。当你把组件放进 app/components/，Nuxt 就知道要自动导入它们；当你把页面放进 app/pages/，Nuxt 就知道要据此生成路由。你不需要在配置文件里逐一声明，目录结构本身就是配置。

这种设计带来的另一个好处是团队协作的标准化。不同开发者创建的项目，目录结构几乎一模一样。新人加入团队时，不需要花时间理解”这个文件为什么放在这里”，因为位置就是答案。

随着项目增长，你可能会在 app/ 下创建一些自定义目录，比如 app/constants/ 存放常量、app/types/ 存放 TypeScript 类型定义。这些不是 Nuxt 的约定目录，但对组织代码同样重要。记住一个原则：Nuxt 约定的目录有特殊功能（自动导入、自动生成），自定义目录则纯粹用于代码组织。