app.config.ts

Nuxt 提供了一个 app.config 配置文件，使您能在应用内部暴露可反应式配置，并具备在生命周期内或通过 Nuxt 插件实时更新以及利用 HMR（热模块替换）进行编辑的能力。

您可以轻松地使用 app.config.ts 文件提供运行时应用配置。该文件可以是 .ts、.js 或 .mjs 扩展名中的任意一个。

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

使用

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

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

We can now universally access theme both when server-rendering the page and in the browser using useAppConfig composable.

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

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

The updateAppConfig utility can be used to update the app.config at runtime.

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

类型标注 App Config

Nuxt 尝试自动从提供的应用配置生成 TypeScript 接口，这样您就不必自己标注类型了。

然而，在某些情况下，您可能希望手动标注类型。这里有两个您可能想要标注的点。

App Config 输入

AppConfigInput 可能被模块作者用来声明设置应用配置时有效的 输入 选项。这不会影响 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 在应用的层次结构中对 AppConfig 使用自定义的合并策略。

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

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

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

Known Limitations

As of Nuxt v3.3, the app.config.ts file is shared with Nitro, which results in the following limitations:

1. You cannot import Vue components directly in app.config.ts.
2. Some auto-imports are not available in the Nitro context.

These limitations occur because Nitro processes the app config without full Vue component support.

While it's possible to use Vite plugins in the Nitro config as a workaround, this approach is not recommended:

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

Related issues:

• Issue #19858
• Issue #19854