---
title: "配置"
description: "Nuxt 配备了合理的默认配置，帮助你高效开发。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/getting-started/configuration"
---
# 配置

> Nuxt 配备了合理的默认配置，帮助你高效开发。

默认情况下，Nuxt 已配置好，可满足大多数使用场景。你可以通过 [`nuxt.config.ts`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/nuxt-config) 文件覆盖或扩展此默认配置。

## Nuxt 配置

[`nuxt.config.ts`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/nuxt-config) 文件位于 Nuxt 项目的根目录，可覆盖或扩展应用的行为。

一个最简配置文件导出包含配置对象的 `defineNuxtConfig` 函数。`defineNuxtConfig` 辅助函数全局可用，无需导入。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  // 我的 Nuxt 配置
})
```

文档中经常会提到该文件，例如添加自定义脚本、注册模块或更改渲染模式。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/api/configuration/nuxt-config"}
每个选项都在**配置参考**中进行了说明。
::

::note
你不必使用 TypeScript 来构建 Nuxt 应用，但强烈推荐将 `nuxt.config` 文件使用 `.ts` 扩展名。这样可以在 IDE 中获得提示，避免配置编辑时的拼写错误和其它错误。
::

### 环境覆盖配置

你可以在 nuxt.config 中配置完全类型化的、按环境划分的覆盖配置：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {
    //
  },
  $env: {
    staging: {
      //
    },
  },
})
```

运行 Nuxt CLI 命令时，通过 `--envName` 参数指定环境，例如：`nuxt build --envName staging`。

有关此覆盖机制的更多信息，请参阅 `c12` 文档中的[环境特定配置](https://github.com/unjs/c12?tab=readme-ov-file#environment-specific-configuration)。

::video-accordion{title="观看 Alexander Lichter 关于环境感知 nuxt.config.ts 的视频" videoId="DFZI2iVCrNc"}
::

::note
如果你正在编写层（layers），也可以使用 `$meta` 键提供你或层的使用者可能会用到的元数据。
::

### 环境变量和私有令牌

`runtimeConfig` API 向应用其余部分暴露诸如环境变量的值。默认情况下，这些键仅在服务端可用。`runtimeConfig.public` 和 `runtimeConfig.app`（Nuxt 内部使用）中的键也在客户端可用。

这些值应在 `nuxt.config` 中定义，并可通过环境变量覆盖。

::code-group
```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    // 仅服务端可用的私有键
    apiSecret: '123',
    // public 内的键也在客户端暴露
    public: {
      apiBase: '/api',
    },
  },
})
```

```ini [.env]
# 这将覆盖 apiSecret 的值
NUXT_API_SECRET=api_secret_token
```
::

这些变量通过 [`useRuntimeConfig()`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-runtime-config) 组合式函数暴露给应用的其余部分。

```vue [pages/index.vue]
<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>
```

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/runtime-config"}
::

## 应用配置

`app.config.ts` 文件位于源码目录（默认项目根目录），用于暴露可以在构建时确定的公共变量。与 `runtimeConfig` 不同，这些变量不能通过环境变量覆盖。

最简配置文件导出包含配置对象的 `defineAppConfig` 函数。`defineAppConfig` 辅助函数全局可用，无需导入。

```ts [app.config.ts]
export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000',
    },
  },
})
```

这些变量通过 [`useAppConfig`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-app-config) 组合式函数暴露给应用的其余部分。

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

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/app-config"}
::

## `runtimeConfig` 与 `app.config` 区别

如前所述，`runtimeConfig` 和 `app.config` 都用于向应用其余部分暴露变量。选择使用哪一个，参考以下准则：

- `runtimeConfig`：需要通过环境变量在构建后指定的私有或公共令牌。
- `app.config`：构建时确定的公共令牌，如网站配置（主题变体、标题）及非敏感的项目配置。

| 功能        | `runtimeConfig` | `app.config` |
| --------- | --------------- | ------------ |
| 客户端       | 已注水（Hydrated）   | 打包（Bundled）  |
| 环境变量支持    | ✅ 是             | ❌ 否          |
| 响应式       | ✅ 是             | ✅ 是          |
| 类型支持      | ✅ 部分            | ✅ 是          |
| 每请求配置     | ❌ 否             | ✅ 是          |
| 热模块替换     | ❌ 否             | ✅ 是          |
| 非基本 JS 类型 | ❌ 否             | ✅ 是          |

## 外部配置文件

Nuxt 使用 [`nuxt.config.ts`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/nuxt-config) 文件作为配置的唯一真实来源，并跳过读取外部配置文件。在构建项目的过程中，你可能需要配置这些内容。下表列出了常见配置，以及适用时如何通过 Nuxt 进行配置。

| 名称                                | 配置文件                    | 配置方法                                                                                           |
| --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| [Nitro](https://nitro.build)      | ~~`nitro.config.ts`~~   | 在 `nuxt.config` 中使用 [`nitro`](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#nitro) 键       |
| [PostCSS](https://postcss.org)    | ~~`postcss.config.js`~~ | 在 `nuxt.config` 中使用 [`postcss`](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#postcss) 键   |
| [Vite](https://vite.dev)          | ~~`vite.config.ts`~~    | 在 `nuxt.config` 中使用 [`vite`](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#vite) 键         |
| [webpack](https://webpack.js.org) | ~~`webpack.config.ts`~~ | 在 `nuxt.config` 中使用 [`webpack`](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#webpack-1) 键 |

其他常见配置文件清单：

| 名称                                           | 配置文件                  | 配置方法                                                                     |
| -------------------------------------------- | --------------------- | ------------------------------------------------------------------------ |
| [TypeScript](https://www.typescriptlang.org) | `tsconfig.json`       | [更多信息](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/tsconfig)   |
| [ESLint](https://eslint.org)                 | `eslint.config.js`    | [更多信息](https://eslint.org/docs/latest/use/configure/configuration-files) |
| [Prettier](https://prettier.io)              | `prettier.config.js`  | [更多信息](https://prettier.io/docs/configuration.html)                      |
| [Stylelint](https://stylelint.io)            | `stylelint.config.js` | [更多信息](https://stylelint.io/user-guide/configure/)                       |
| [TailwindCSS](https://tailwindcss.com)       | `tailwind.config.js`  | [更多信息](https://tailwindcss.nuxtjs.org/tailwindcss/configuration/)        |
| [Vitest](https://vitest.dev)                 | `vitest.config.ts`    | [更多信息](https://vitest.dev/config/)                                       |

## Vue 配置

### 使用 Vite

如果需要向 `@vitejs/plugin-vue` 或 `@vitejs/plugin-vue-jsx` 传递参数，可以在 `nuxt.config` 中这样配置：

- `vite.vue` 用于 `@vitejs/plugin-vue`。查看[可用选项](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)。
- `vite.vueJsx` 用于 `@vitejs/plugin-vue-jsx`。查看[可用选项](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx)。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
    vueJsx: {
      mergeProps: true,
    },
  },
})
```

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/api/configuration/nuxt-config#vue-1"}
::

### 使用 webpack

如果使用 webpack 并需要配置 `vue-loader`，可以在 `nuxt.config` 中使用 `webpack.loaders.vue` 键进行配置。可用选项定义见 [此处](https://github.com/vuejs/vue-loader/blob/main/src/index.ts#L32-L62)。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      },
    },
  },
})
```

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/api/configuration/nuxt-config#loaders"}
::

### 启用 Vue 实验性特性

你可能需要启用 Vue 实验性功能，如 `propsDestructure`。无论使用哪个构建器，Nuxt 都提供了简便的方式在 `nuxt.config.ts` 中完成配置：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})
```

#### Vue 3.4 与 Nuxt 3.9 中实验性 `reactivityTransform` 迁移

自 Nuxt 3.9 和 Vue 3.4 起，`reactivityTransform` 已从 Vue 移至 Vue Macros，并提供了 [Nuxt 集成](https://vue-macros.dev/guide/nuxt-integration.html)。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/api/configuration/nuxt-config#vue-1"}
::


## Sitemap

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