核心文件

为什么需要了解核心文件？

Nuxt 项目的核心文件不多，但每一个都至关重要。了解它们的作用和配置方式，你就掌握了项目的"控制面板"。

app.vue — 根组件

app/app.vue 是 Nuxt 应用的根组件，所有页面都在其中渲染。

<!-- 最简形式 -->
<template>
  <NuxtPage />
</template>

带布局的完整形式：

<template>
  <div>
    <NuxtRouteAnnouncer />
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

每一行的作用

组件	作用	可以省略吗？
<NuxtRouteAnnouncer />	无障碍：让屏幕阅读器播报页面变化	可以，但影响无障碍
<NuxtLayout>	包裹布局组件（导航栏、页脚等）	可以，去掉则不使用布局系统
<NuxtPage />	渲染当前路由对应的页面组件	❌ 不能，否则页面不显示

<NuxtRouteAnnouncer /> 是 Nuxt 4.4 新增的

它会在路由变化时自动播报新页面的标题，对视障用户非常友好。推荐加上。

INFO

️ 新手常犯的错误：

1. 在 app.vue 中写导航栏 → 应该写在布局（layouts/default.vue）中
2. 在 app.vue 中写页面内容 → 应该写在页面（pages/xxx.vue）中
3. 忘记写 <NuxtPage /> → 页面空白

app.vue 只做一件事：当容器，把布局和页面组合在一起。

error.vue — 错误页面

app/error.vue 用于展示全局错误：

<script setup lang="ts">
const error = useError()

const handleError = () => clearError({ redirect: '/' })
</script>

<template>
  <div class="error-page">
    <h1>{{ error?.statusCode }}</h1>
    <p>{{ error?.message }}</p>
    <button @click="handleError">返回首页</button>
  </div>
</template>

error.vue 的特殊性（必须了解）

特性	说明	原因
不是普通页面	不在 pages/ 目录中	错误可能在页面渲染前就发生
不受布局包裹	需要自带完整 HTML	布局可能也有错误
不受路由中间件保护	某些中间件可能不可用	中间件可能导致了错误
某些组合式函数不可用	如 useFetch	依赖的数据可能不存在

INFO

️ 安全提示：在生产环境中 不要在错误页面显示详细的错误信息（如堆栈跟踪），这可能暴露服务器信息。error.stack 只在开发模式下可用

app.config.ts — 应用配置

app/app.config.ts 定义构建时确定的应用配置：

export default defineAppConfig({
  theme: {
    primaryColor: '#00DC82',
    darkMode: false,
  },
})

通过 useAppConfig() 访问：

const appConfig = useAppConfig()
console.log(appConfig.theme.primaryColor) // '#00DC82'

app.config.ts vs nuxt.config.ts 中的 runtimeConfig

对比	app.config.ts	runtimeConfig
何时确定	构建时	运行时
环境变量覆盖	❌ 不支持	✅ 支持
私有配置	❌ 全部公开	✅ 服务端独有
适合放	主题色、UI 布局参数	API 地址、密钥
修改后	需要重新构建	重启服务即可

简单判断

如果值随环境变化（开发/测试/生产不同），用 runtimeConfig；如果基本不变（如主题色），用 app.config.ts。

nuxt.config.ts — Nuxt 配置

项目主配置文件，详见 项目配置。

nuxt.config.ts 是 Nuxt 的"大脑"

几乎所有全局行为都在这里控制：

• 启用哪些模块
• SSR 还是 CSR
• 路由规则
• 构建配置
• 环境变量映射

修改 nuxt.config.ts 后需要重启开发服务器。

.env — 环境变量

# .env
NUXT_API_SECRET=my-secret
NUXT_PUBLIC_API_BASE=https://api.example.com
NUXT_PUBLIC_APP_NAME=MyApp

环境变量自动映射到 runtimeConfig：

NUXT_ + 配置路径（大写，下划线连接）

.env 的工作机制

1. Nuxt 开发服务器启动时自动读取 .env
2. 变量覆盖 nuxt.config.ts 中 runtimeConfig 的默认值
3. 生产环境通常直接在服务器上设置环境变量（不用 .env）

INFO

️ 安全原则

• .env 不要提交到 Git（确认 .gitignore 中有 .env）
• 提供 .env.example 文件，列出需要的变量但不含真实值
• 敏感信息（密钥、密码）永远不要放在 public 下的 runtimeConfig

.env 的加载顺序

1. 系统环境变量（优先级最高）
2. .env 文件
3. nuxt.config.ts 中的默认值

如果同一个变量在多处设置，优先级高的覆盖优先级低的。

.nuxtrc — 简化配置

扁平键值对格式的配置文件：

# 项目级 .nuxtrc
devtools.enabled=true
modules[]=@pinia/nuxt

# 用户级 ~/.nuxtrc（全局生效，不影响项目）
telemetry.enabled=false

什么时候用 .nuxtrc？

• 项目配置 → 用 nuxt.config.ts（有类型提示）
• 个人偏好（不影响项目） → 用 ~/.nuxtrc（全局生效）
• .nuxtrc 的语法更适合简单的键值对，复杂配置还是 nuxt.config.ts 更清晰

.nuxtignore — 忽略文件

指定 Nuxt 构建时忽略的文件：

# .nuxtignore
app/pages/draft.vue          # 不生成这个页面的路由
app/components/deprecated/**  # 不自动导入这些组件
app/layouts/old-*.vue         # 不注册这些布局

.nuxtignore vs .gitignore

文件	作用	效果
.gitignore	Git 忽略	文件不会被提交到仓库
.nuxtignore	Nuxt 忽略	文件还在项目中，但不参与构建

使用场景

你有一个正在开发中的页面，不想让 Nuxt 生成路由，就在 .nuxtignore 中忽略它。等开发完了再删除忽略规则。

tsconfig.json — TypeScript 配置

Nuxt 4 只需要在项目根目录放一个 tsconfig.json，Nuxt 会自动生成完整的配置：

{
  "extends": "./.nuxt/tsconfig.json"
}

运行 nuxt prepare 后，.nuxt/tsconfig.json 会自动生成，包含：

• app/ 的类型和路径映射
• server/ 的类型和路径映射
• shared/ 的类型和路径映射

Nuxt 4 的 TypeScript 配置体系

tsconfig.json（你的，只写 extends）
└── .nuxt/tsconfig.json（自动生成的总配置）
├── app/ 的类型和路径
├── server/ 的类型和路径
└── shared/ 的类型和路径

INFO

️ 不要手动修改 .nuxt/tsconfig.json 它会在每次 nuxt prepare 时重新生成

TIP

如果类型提示不正常 运行 nuxt prepare 重新生成即可

核心文件速查表

文件	位置	作用	修改后需要
app.vue	app/	应用根组件	重启开发服务器
error.vue	app/	错误页面	HMR 自动更新
app.config.ts	app/	应用 UI 配置	重新构建
nuxt.config.ts	项目根	Nuxt 主配置	重启开发服务器
.env	项目根	环境变量	重启开发服务器
.nuxtrc	项目根/用户目录	简化配置	重启开发服务器
.nuxtignore	项目根	忽略构建文件	重启开发服务器
tsconfig.json	项目根	TypeScript 配置	通常不需要改