app.config.ts

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

Nuxt 提供了一个 app/app.config.ts 配置文件，以便在你的应用程序中暴露响应式配置，并且能够在生命周期中运行时使用 nuxt 插件对其进行更新，并使用 HMR（热模块替换）进行编辑。

你可以使用 app.config.ts 文件轻松提供运行时应用配置。它可以具有 .ts、.js 或 .mjs 扩展名中的任何一个。

app/app.config.ts

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

不要在 app.config 文件中放置任何机密值。它暴露给用户客户端包。

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

使用方法

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

app/app.config.ts

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

我们现在可以使用 useAppConfig`` 组合式函数在服务器呈现页面时和浏览器中普遍访问 theme`。

app/pages/index.vue

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

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

updateAppConfig`` 实用程序可用于在运行时更新 app.config`。

app/pages/index.vue

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

阅读有关 updateAppConfig 实用程序的更多信息。 ::

键入应用配置

Nuxt 尝试从提供的应用配置自动生成 TypeScript 接口，因此你不必自己键入它。

但是，在某些情况下，你可能想要自己键入它。你可能想要键入两种可能的东西。

应用配置输入

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

index.d.ts

declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** Theme configuration */
    theme?: {
      /** Primary app color */
      primaryColor?: string
    }
  }
}

// 在扩充类型时，始终确保你导入/导出某些内容
export {}

应用配置输出

如果你想键入调用 useAppConfig()`` 的结果，那么你将想要扩充 AppConfig`。

在键入 AppConfig 时要小心，因为你将覆盖 Nuxt 从你实际定义的应用配置推断的类型。

index.d.ts

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

// 在扩充类型时，始终确保你导入/导出某些内容
export {}

合并策略

Nuxt 在应用程序的层中使用自定义合并策略来处理 AppConfig。

此策略使用函数合并器实现，该合并器允许为 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 处理应用配置时没有完整的 Vue 组件支持。

虽然可以在 Nitro 配置中使用 Vite 插件作为变通方法，但不建议采用此方法：

nuxt.config.ts

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

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