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',
  },
})

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

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 会尝试自动从提供的应用配置生成 TypeScript 接口，这样你不必手动定义类型。

但有些情况下你想自己定义类型。可能想要定义两种类型。

App Config 输入类型

AppConfigInput 可能由模块作者使用，用于声明设置应用配置时有效的输入选项。这不会影响 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 在应用的层（layers）中使用自定义的合并策略来处理 AppConfig。

此策略使用 Function Merger 实现，允许为 app.config 中值为数组的每个键定义自定义合并策略。

函数合并器只能在扩展层（extended layers）中使用，不能用于项目中的主 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 处理应用配置时不完整支持 Vue 组件。

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

nuxt.config.ts

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

使用此变通方法可能会导致意外行为和错误。Vue 插件只是 Nitro 上下文中不可用的众多插件之一。