app.config.ts

Nuxt 提供了一个 app.config 配置文件，用于在应用中公开响应式配置，并能够在生命周期内运行时更新它，或者使用 nuxt 插件并通过 HMR（热模块替换）进行编辑。

¥Nuxt provides an app.config config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).

你可以使用 app.config.ts 文件轻松提供运行时应用配置。它可以包含 .ts、.js 或 .mjs 扩展名。

¥You can easily provide runtime app configuration using app.config.ts file. It can have either of .ts, .js, or .mjs extensions.

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

用法

¥Usage

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

¥To expose config and environment variables to the rest of your app, you will need to define configuration in app.config file.

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

现在，无论是在服务器渲染页面时，还是在浏览器中使用 useAppConfig 可组合组件，我们都可以普遍访问 theme。

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

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

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

:

了解更多关于 updateAppConfig 实用程序的信息。

¥Read more about the updateAppConfig utility.

::

Typing 应用配置

¥Typing App Config

Nuxt 会尝试根据提供的应用配置自动生成 TypeScript 接口，这样你就无需自己手动编写代码。

¥Nuxt tries to automatically generate a TypeScript interface from provided app config so you won't have to type it yourself.

然而，在某些情况下，你可能需要自己输入。你可能需要输入两项内容。

¥However, there are some cases where you might want to type it yourself. There are two possible things you might want to type.

应用配置输入

¥App Config Input

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

¥AppConfigInput might be used by module authors who are declaring what valid input options are when setting app config. This will not affect the type of useAppConfig().

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 Config Output

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

¥If you want to type the result of calling useAppConfig(), then you will want to extend AppConfig.

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 {}

合并策略

¥Merging Strategy

Nuxt 使用自定义策略合并应用 层 中的 AppConfig。

¥Nuxt uses a custom merging strategy for the AppConfig within the layers of your application.

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

¥This strategy is implemented using a Function Merger, which allows defining a custom merging strategy for every key in app.config that has an array as value.

以下是使用示例：

¥Here's an example of how you can use:

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

export default defineAppConfig({
  // Overwrite default array value by using a merger function
  array: () => ['bonjour'],
})

已知限制

¥Known Limitations

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

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

1. 你无法在 app.config.ts 中直接导入 Vue 组件。
2. 某些自动导入功能在 Nitro 环境中不可用。

出现这些限制是因为 Nitro 在没有完整的 Vue 组件支持的情况下处理应用配置。

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

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

¥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:

• 问题 #19858
• 问题 #19854