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 Input

AppConfigInput 可能会被模块作者使用，用于声明在设置 app config 时哪些是有效的“输入”选项。这不会影响 useAppConfig() 的返回类型。

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

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

App Config Output

如果您想为调用 useAppConfig() 的结果添加类型，则需要扩展 AppConfig。

declare module 'nuxt/schema' {
  interface AppConfig {
    // 这将完全替换现有推断出的 `theme` 属性
    theme: {
      // 您可能希望为此值添加类型，以提供比 Nuxt 能推断出的更具体的类型，
      // 例如字符串字面量类型
      primaryColor?: 'red' | 'blue'
    }
  }
}

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

合并策略

Nuxt 对应用中各个层（layers）内的 AppConfig 使用自定义合并策略。

该策略使用 函数合并器 实现，允许为 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 在处理 app config 时不具备完整的 Vue 组件支持。

尽管可以在 Nitro 配置中使用 Vite 插件作为一种变通方法，但不推荐这种做法：

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

相关问题：

• Issue #19858
• Issue #19854