app.config.ts

Nuxt 提供了一个 app/app.config.ts 配置文件，用于在应用内部暴露响应式配置，并能在生命周期中、或使用 Nuxt 插件时于运行时更新它，同时支持通过 HMR（热模块替换）进行编辑。

你可以使用 app.config.ts 文件轻松提供运行时应用配置。它可以使用 .ts、.js 或 .mjs 扩展名。

export default defineAppConfig({
  foo: 'bar',
})

用法

要向应用的其他部分暴露配置和环境变量，你需要在 app.config 文件中定义配置。

export default defineAppConfig({
  theme: {
    primaryColor: '#ababab',
  },
})

现在我们可以使用 useAppConfig 组合式函数，在服务端渲染页面时和浏览器中通用地访问 theme。

<script setup lang="ts">
const appConfig = useAppConfig()

console.log(appConfig.theme)
</script>

updateAppConfig 工具函数可在运行时用于更新 app.config。

<script setup>
const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
</script>

类型化 App Config

Nuxt 会尝试从你提供的 app config 自动生成 TypeScript 接口，因此你无需自己手动类型化。

完全推断出的类型仅在应用代码（组件、组合式函数、插件等）中可用。在服务端路由、shared/ 目录中的代码以及 nuxt.config 里，app.config 文件中定义的键会被类型化为 unknown：在应用上下文之外对这些键进行类型检查需要检查你的应用代码，而那里没有应用自动导入可用。nuxt.config 的 appConfig 选项中内联定义的键则在所有地方都有类型。如果你需要在应用代码之外为其它键提供类型，可以如下文所述扩展 AppConfig 接口。增强文件的位置决定了哪些上下文能看到它：放在 shared/ 目录中的 .d.ts 文件会覆盖应用代码、共享代码和服务端路由。

不过，在某些情况下你可能想自己类型化。你可能需要类型化两种情况。

App Config 输入

AppConfigInput 可能被模块作者用来声明在设置 app config 时有效的_输入_选项是什么。这不会影响 useAppConfig() 的类型。

declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** 主题配置 */
    theme?: {
      /** 应用主色 */
      primaryColor?: string
    }
  }
}

// 在增强类型时，确保导入/导出某些内容始终很重要
export {}

App Config 输出

如果你想为调用 useAppConfig() 的结果类型化，那么你需要扩展 AppConfig。

declare module 'nuxt/schema' {
  interface AppConfig {
    // 这会完全替换已推断的 `theme` 属性
    theme: {
      // 你可能想为这个值类型化，以添加比 Nuxt 能推断的更具体的类型，
      // 例如字符串字面量类型
      primaryColor?: 'red' | 'blue'
    }
  }
}

// 在增强类型时，确保导入/导出某些内容始终很重要
export {}

合并策略

Nuxt 对你应用 layers 中的 AppConfig 使用了自定义的合并策略。

该策略通过 Function Merger 实现，它允许为 app.config 中每个值为数组的键定义自定义合并策略。

以下是如何使用的一个示例：

export default defineAppConfig({
  // 默认数组值
  array: ['hello'],
})

export default defineAppConfig({
  // 通过使用合并函数来覆盖默认数组值
  array: () => ['bonjour'],
})

已知限制

截至 Nuxt v3.3，app.config.ts 文件与 Nitro 共享，这导致了以下限制：

1. 你不能在 app.config.ts 中直接导入 Vue 组件。
2. Nitro 上下文中某些自动导入不可用。

这些限制产生的原因是 Nitro 在没有完整 Vue 组件支持的情况下处理 app config。

虽然作为变通方案，你可以在 Nitro 配置中使用 Vite 插件，但不推荐这种做法：

export default defineNuxtConfig({
  nitro: {
    vite: {
      plugins: [vue()],
    },
  },
})

相关问题：

• Issue #19858
• Issue #19854