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 文件中放置任何秘密值。它会被暴露给用户客户端包。

When configuring a custom srcDir, make sure to place the app.config file at the root of the new srcDir path.

使用

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

app.config.ts

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.

pages/index.vue

<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.

pages/index.vue

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

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

Read more about the updateAppConfig utility.

类型标注 App Config

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

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

App Config 输入

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

index.d.ts

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

// 增强类型时始终确保导入/导出某些内容是很重要的
export {}

App Config 输出

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

在标注 AppConfig 时要小心，因为您会覆盖 Nuxt 从实际定义的应用配置推断出的类型。

index.d.ts

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

// 增强类型时始终确保导入/导出某些内容是很重要的
export {}

合并策略

Nuxt 在应用的层次结构中对 AppConfig 使用自定义的合并策略。

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

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

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

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

已知限制

截至 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 上下文中不可用的插件之一。