Nuxt 中 .nuxtrc 文件详解：扁平配置语法、全局配置与模块生命周期状态管理

.nuxtrc 是 Nuxt 提供的轻量级配置文件，用类 .npmrc 的扁平键值语法即可设置 Nuxt 选项，无需编写 TypeScript。本文基于 Nuxt 仓库中的官方文档与配置加载源码，讲清 .nuxtrc 的语法格式、与 nuxt.config 的优先级关系、全局用户级配置的用法，以及它在源码中如何被 c12/rc9 解析、如何在构建缓存与模块安装生命周期中被读取和写入。

.nuxtrc 是什么：基于 rc9 的扁平配置语法

Nuxt 的主要配置入口是 nuxt.config，它是一个可执行 TypeScript 的完整配置。而 .nuxtrc 面向的是简单场景：当你只想覆盖少量选项（比如关闭 SSR、开启 DevTools、声明几个模块）时，用扁平的 key=value 语法即可，不必写脚本文件。

从源码看，.nuxtrc 的解析基于 rc9 库（当前仓库锁定版本为 ^3.0.1，见 pnpm-workspace.yaml），并通过 c12 集成进 Nuxt 的配置加载流程。在 loadNuxtConfig 的选项定义 中可以看到两个直接相关的参数：

• rcFile：与配置文件一起加载的 rc 文件名，默认值为 '.nuxtrc'，设为 false 可完全不加载；
• globalRc：是否同时加载用户级和工作区级 rc 文件，默认值为 true。

在实际加载调用中，loadRootConfig 函数 将其传入 c12 的 loadConfig：

// packages/kit/src/loader/config.ts
() => loadConfig<NuxtConfig>({
  name: 'nuxt',
  configFile: configFileName,
  rcFile: opts.rcFile ?? '.nuxtrc',
  globalRc: opts.globalRc ?? true,
  // ...
})

这意味着每个 Nuxt 项目启动时，.nuxtrc 都是配置加载链路的固定一环，无需任何额外声明。

使用示例：完整的 .nuxtrc 写法

一个典型的项目级 .nuxtrc 文件（官方文档中的完整示例）如下：

# Disable SSR
ssr=false

# Configuration for `@nuxt/devtools`
devtools.enabled=true

# Add Nuxt modules
modules[]=@nuxt/image
modules[]=nuxt-security

# Module setups (automatically added by Nuxt)
setups.@nuxt/test-utils="3.23.0"

各行的含义逐条说明：

写法	说明
ssr=false	关闭服务端渲染。rc9 的扁平语法会自动将 false、true、数字等解析为对应类型，而非字符串
devtools.enabled=true	点号表示嵌套属性，等价于 nuxt.config 中的 devtools: { enabled: true }
modules[]=@nuxt/image	[] 表示数组追加语法，一行添加一个模块，等价于 modules: ['@nuxt/image', 'nuxt-security']
setups.@nuxt/test-utils="3.23.0"	模块安装状态记录区，由 Nuxt 自动写入，见下文详解

这里有一个值得注意的实现细节：Nuxt 覆盖 c12 默认的合并行为，使用了一个自定义 merger。它对数组做拼接（concat）而非覆盖：

// packages/kit/src/loader/config.ts
const merger = createDefu((obj, key, value) => {
  if (Array.isArray(obj[key]) && Array.isArray(value)) {
    obj[key] = obj[key].concat(value)
    return true
  }
})

因此 .nuxtrc 中的 modules[] 条目与 nuxt.config 中的 modules 数组会被合并而非互相顶掉——这也是为什么在 rc 文件里声明模块是安全的。

与 nuxt.config 的优先级

规则很明确：如果 nuxt.config 中存在同名属性，它会覆盖 .nuxtrc 中的值。在层级加载顺序中，c12 会按「高优先级层在前」的顺序合并各来源，项目根的 nuxt.config 位于 .nuxtrc 之上。

还有一个源码层面的佐证：配置层过滤逻辑 会显式跳过「配置文件就是 .nuxtrc」的层——即一个只有 .nuxtrc 而没有 nuxt.config 的目录，其值参与配置合并，但不会成为一个正式的 layer（不产生 #layers/* 别名、不进入 _layers 列表）：

// packages/kit/src/loader/config.ts
// Filter layers
if (!layer.configFile || layer.configFile.endsWith('.nuxtrc')) { continue }

setups 区段：不要手动修改

文档中特别强调：Nuxt 会自动向 .nuxtrc 添加 setups 区段，用于记录各模块的安装与升级状态，供 模块生命周期钩子 使用，不应手工修改。

这部分在源码中的实现位于 callLifecycleHooks。每当一个带 meta.name 和 meta.version 的模块被安装时，Kit 会执行以下流程：

// packages/kit/src/module/install.ts
const rc = readRc({ dir: nuxt.options.rootDir, name: '.nuxtrc' })
const previousVersion = rc?.setups?.[meta.name]

try {
  if (!previousVersion) {
    await nuxtModule.onInstall?.(nuxt)
  } else if (isGreater(meta.version, previousVersion)) {
    await nuxtModule.onUpgrade?.(nuxt, inlineOptions, previousVersion)
  }
  if (previousVersion !== meta.version) {
    updateRc(
      { setups: { [meta.name]: meta?.version } },
      { dir: nuxt.options.rootDir, name: '.nuxtrc' },
    )
  }
} catch (e) {
  kitDiagnostics.NUXT_B8019({ ... })
}

逻辑可以拆解为四步：

1. 用 rc9 的 read 从项目根目录（nuxt.options.rootDir）读取 .nuxtrc；
2. 若 setups 中没有该模块的记录，说明是首次安装，触发模块的 onInstall 钩子；
3. 若已有记录且当前版本大于记录版本（verkit 的 isGreater 做 semver 比较），触发 onUpgrade 钩子并传入旧版本号；
4. 版本发生变化时，用 rc9 的 update 将新版本号写回 .nuxtrc 的 setups 区段。

该行为有专门的测试用例覆盖：packages/kit/test/module.test.ts 验证了三个场景——首次安装后 .nuxtrc 中写入 setups['test-module'] = '1.0.0'、再次安装时 onInstall 不再触发、旧版本 0.1.0 升级到 1.0.0 时 onUpgrade 被调用且版本号被更新。对模块作者来说，这意味着 .nuxtrc 里的 setups 行是「模块状态数据库」，钩子只会在真正的新增或升级时执行一次。

全局 .nuxtrc 文件

除了项目级文件，你还可以在用户主目录创建全局 .nuxtrc，让默认设置作用于本机的所有 Nuxt 项目：

• macOS / Linux：~/.nuxtrc
• Windows：C:\Users\{username}\.nuxtrc

这一能力正是上文 globalRc 默认值为 true 的体现——c12 在加载时会自动向上发现用户级 rc 文件并作为最低优先级来源参与合并。完整的优先级从高到低为：

1. nuxt.config（及通过 extends 引入的各层配置）；
2. 项目级 .nuxtrc；
3. 全局（用户主目录）.nuxtrc。

适合放入全局文件的内容包括：个人偏好的 devtools 设置、默认模块列表等；而项目专属的 ssr、modules 等选项仍应写在项目目录中，以便进入版本控制并随项目分发。

.nuxtrc 对构建缓存的影响

一个容易被忽略的事实：.nuxtrc 的内容变化会导致构建缓存失效。在 构建哈希计算逻辑 中，每个 layer 根目录下的以下文件都会参与 hash 计算：

// packages/nuxt/src/core/cache.ts
const rootFiles = await readFilesRecursive(layer.config?.rootDir || layer.cwd, {
  // ...
  patterns: [
    '.nuxtrc',
    '.npmrc',
    'package.json',
    // ... lockfiles, tsconfig.json
  ],
})

因此修改 .nuxtrc（包括 Nuxt 自动更新 setups 区段的行为）都会触发缓存重建，这是符合直觉的正确行为。

小结与延伸阅读

• .nuxtrc 适合少量、扁平的配置：关闭 SSR、开启 DevTools、声明模块，语法由 rc9 解析，支持嵌套点号与 [] 数组追加；
• 优先级为 nuxt.config > 项目级 .nuxtrc > 全局 ~/.nuxtrc；
• setups 区段是 Nuxt 为模块 onInstall/onUpgrade 钩子维护的状态记录，由 packages/kit/src/module/install.ts 自动读写，请勿手工编辑；
• 修改 .nuxtrc 会改变构建缓存哈希。

更多可用选项见 Nuxt 配置完整参考，模块生命周期钩子的 API 说明见 Kit 模块文档。