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 组合式 API 通用访问 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 工具的更多信息。

Typing App Config

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

然而，在某些情况下，您可能希望自己进行键入。您可能希望键入的有两种可能的内容。

应用配置输入

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

index.d.ts

declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** 主题配置 */
    theme?: {
      /** 主应用颜色 */
      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 上下文中不可用的插件之一。