---
title: "app.config.ts"
description: "使用 App Config 文件在您的应用中公开可响应的配置。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/app-config"
---
# app.config.ts

> 使用 App Config 文件在您的应用中公开可响应的配置。

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

您可以使用 `app.config.ts` 文件轻松提供运行时应用配置。该文件可以使用 `.ts`、`.js` 或 `.mjs` 其中之一作为扩展名。

```ts twoslash [app/app.config.ts]
export default defineAppConfig({
  foo: 'bar',
})
```

::caution
不要在 `app.config` 文件中放置任何敏感值。它会被暴露到客户端打包中。
::

::note
配置自定义 [`srcDir`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#srcdir) 时，请确保将 `app.config` 文件放在新的 `srcDir` 路径的根目录下。
::

## 使用

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

```ts twoslash [app/app.config.ts]
export default defineAppConfig({
  theme: {
    primaryColor: '#ababab',
  },
})
```

现在，我们可以使用 [`useAppConfig`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-app-config) 组合式函数，在服务端渲染页面时和浏览器中通用地访问 `theme`。

```vue [app/pages/index.vue]
<script setup lang="ts">
const appConfig = useAppConfig()

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

[`updateAppConfig`](https://nuxt.zhcndoc.com/docs/4.x/api/utils/update-app-config) 工具可用于在运行时更新 `app.config`。

```vue [app/pages/index.vue]
<script setup>
const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/api/utils/update-app-config"}
详细了解 `updateAppConfig` 工具。
::

## 为 App Config 添加类型

Nuxt 会尝试根据提供的 app config 自动生成 TypeScript 接口，这样您就不必自己手动声明类型。

完整推断出的类型仅在应用代码中可用（组件、组合式函数、插件等）。在服务端路由、`shared/` 目录中的代码以及 `nuxt.config` 中，`app.config` 文件中定义的键会被视为 `unknown`：在这些位置为其添加类型，需要在应用上下文之外对应用代码进行类型检查，而此时无法使用应用自动导入。直接在 `nuxt.config` 的 `appConfig` 选项中定义的键则在所有位置都有类型。如果您需要在应用代码之外为其他键添加类型，可以按照下文所述扩展 `SharedAppConfig` 接口。增强类型文件的位置决定了哪些上下文可以使用它：放在 `shared/` 目录中的 `.d.ts` 文件适用于应用代码、共享代码和服务端路由。

不过，在某些情况下，您可能希望自己为其添加类型。您可能想要类型化的内容有两种。

### App Config 输入

`AppConfigInput` 可能由模块作者使用，用于声明在设置 app config 时哪些是有效的“输入”选项。这不会影响 `useAppConfig()` 的返回类型。

```ts [index.d.ts]
declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** 主题配置 */
    theme?: {
      /** 应用主色 */
      primaryColor?: string
    }
  }
}

// 在增强类型时，始终要确保你导入/导出了某些内容
export {}
```

### App Config 输出

如果您想为应用代码中调用 [`useAppConfig()`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-app-config) 的结果添加类型，则需要扩展 `AppConfig`。在应用代码之外（服务端路由、`shared/` 目录和 `nuxt.config` 中），`useAppConfig()` 返回的是 `SharedAppConfig`，因此应改为扩展该接口。

::warning
在为 `AppConfig` 定义类型时要小心，因为这将覆盖 Nuxt 根据您实际定义的 app config 推断出的类型。
::

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

// 在增强类型时，始终要确保你导入/导出了某些内容
export {}
```

## 合并策略

Nuxt 在应用的[各个层](https://nuxt.zhcndoc.com/docs/4.x/getting-started/layers)中使用自定义策略合并 `AppConfig`。

该策略使用 [Function Merger](https://github.com/unjs/defu#function-merger) 实现，允许为 `app.config` 中值为数组的每个键定义自定义合并策略。

::note
函数合并器只能在扩展层（extended layers）中使用，而不能在项目的主 `app.config` 中使用。
::

下面是一个使用示例：

::code-group
```ts twoslash [layer/app/app.config.ts]
export default defineAppConfig({
  // 默认数组值
  array: ['hello'],
})
```

```ts twoslash [app/app.config.ts]
export default defineAppConfig({
  // 使用合并函数覆盖默认数组值
  array: () => ['bonjour'],
})
```
::

## 已知限制

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

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

这些限制是因为 Nitro 在处理 app config 时不具备完整的 Vue 组件支持。

尽管可以在 Nitro 配置中使用 Vite 插件作为一种变通方法，但不推荐这种做法：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    vite: {
      plugins: [vue()],
    },
  },
})
```

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

相关问题：

- [Issue #19858](https://github.com/nuxt/nuxt/issues/19858)
- [Issue #19854](https://github.com/nuxt/nuxt/issues/19854)

::note
Nitro v3 将通过移除对 app config 的支持来解决这些限制。
您可以在此拉取请求中跟踪进度：[this pull request](https://github.com/nitrojs/nitro/pull/2521)。
::


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.