app.config.ts

使用 App Config 文件在应用中暴露响应式配置。

Nuxt 提供了一个 app.config 配置文件，用于在应用中暴露响应式配置，可在生命周期内或通过 Nuxt 插件动态更新，并支持热模块替换（HMR）。

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

app.config.ts

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

请勿在 app.config 文件中放置任何机密信息。该文件会暴露在客户端打包中。

如果你配置了自定义的 srcDir，请确保将 app.config 文件放在新的 srcDir 路径的根目录中。

用法

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

app.config.ts

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

我们现在可以在服务端渲染和浏览器端通过 useAppConfig 组合式函数访问 theme：

pages/index.vue

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

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

你可以使用 updateAppConfig 工具在运行时更新 app.config：

pages/index.vue

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

阅读更多关于 updateAppConfig 工具的内容。

App Config 类型定义

Nuxt 会尝试自动根据你提供的 app config 生成 TypeScript 接口，因此你通常无需手动定义类型。

但在某些场景下，你可能需要自行定义类型。你可以定义以下两类类型：

App Config 输入类型

AppConfigInput 通常用于模块作者，声明设置 app config 时允许的输入选项。它不会影响 useAppConfig() 的返回类型。

index.d.ts

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

// 在扩展类型时始终需要导入或导出某些内容
export {}

App Config 输出类型

若你想为 useAppConfig() 的返回结果定义类型，应扩展 AppConfig 接口。

为 AppConfig 添加类型时要小心，这会覆盖 Nuxt 根据你的配置推断出的类型。

index.d.ts

declare module 'nuxt/schema' {
  interface AppConfig {
    // 这将完全替换推断出的 `theme` 属性
    theme: {
      // 可使用更具体的字面量类型代替默认推断结果
      primaryColor?: 'red' | 'blue'
    }
  }
}

// 在扩展类型时始终需要导入或导出某些内容
export {}

合并策略

在多层架构中，Nuxt 为 AppConfig 使用了自定义的合并策略。

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

函数合并器只能用于扩展层，不能用于项目中的主 app.config 文件。

以下是一个使用示例：

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

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

已知限制

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

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

这些限制的根本原因在于 Nitro 处理 app config 时无法完全支持 Vue 组件。

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

nuxt.config.ts

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

使用此类变通方法可能会导致意外行为或 bug。Vue 插件只是 Nitro 不支持的众多插件之一。