app.config.ts · Nuxt 目录结构

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 组合式时，我们可以普遍访问 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 实用程序的更多信息。

键入 App 配置

Nuxt 尝试根据提供的应用程序配置自动生成 TypeScript 接口，因此您无需自己键入。

但是，在某些情况下，您可能希望自己键入它。您可能希望键入两件事。

App 配置输入

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

index.d.ts

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

// It is always important to ensure you import/export something when augmenting a type
export {}

App 配置输出

如果要键入调用 useAppConfig() 的结果，则需要扩展 AppConfig。

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

index.d.ts

declare module 'nuxt/schema' {
  interface AppConfig {
    // This will entirely replace the existing inferred `theme` property
    theme: {
      // You might want to type this value to add more specific types than Nuxt can infer,
      // such as string literal types
      primaryColor?: 'red' | 'blue'
    }
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}

合并策略

Nuxt 在应用程序的各层中对 AppConfig 使用自定义合并策略。

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

函数合并器只能在扩展层中使用，而不能在项目中的主 app.config 中使用。

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

export default defineAppConfig
({
  // Default array value
  array
: ['hello'],
})

已知限制

从 Nuxt v3.3 开始，app.config.ts 文件与 Nitro 共享，这导致以下限制

您不能直接在 app.config.ts 中导入 Vue 组件。
某些自动导入在 Nitro 上下文中不可用。

这些限制是由于 Nitro 在没有完全支持 Vue 组件的情况下处理应用程序配置造成的。

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

nuxt.config.ts

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

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