---
title: "配置"
description: "Nuxt 已使用合理的默认配置来提升你的生产力。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/getting-started/configuration"
---
# 配置

> Nuxt 已使用合理的默认配置来提升你的生产力。

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

## Nuxt 配置

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

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

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  // My Nuxt config
})
```

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

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/api/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
如果你正在编写 layer（层），也可以使用 `$meta` 键来提供你或使用你 layer 的消费者可能会使用的元数据。
::

### 环境变量与私密令牌

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

这些值应在 `nuxt.config` 中定义，并且可以使用环境变量来覆盖。

::code-group
```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available server-side
    apiSecret: '123',
    // Keys within public are also exposed client-side
    public: {
      apiBase: '/api',
    },
  },
})
```

```ini [.env]
# This will override the value of apiSecret
NUXT_API_SECRET=api_secret_token
```
::

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

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

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

## 应用配置

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

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

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

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

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

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

## `runtimeConfig` 与 `app.config`

如上所述，`runtimeConfig` 和 `app.config` 都用于向应用的其余部分暴露变量。为了确定应该使用哪一个，以下是一些指南：

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

| 特性        | `runtimeConfig` | `app.config` |
| --------- | --------------- | ------------ |
| 客户端       | 已水合             | 已打包          |
| 环境变量      | ✅ 是             | ❌ 否          |
| 响应式       | ✅ 是             | ✅ 是          |
| 类型支持      | ✅ 部分            | ✅ 是          |
| 按请求配置     | ❌ 否             | ✅ 是          |
| 热模块替换     | ❌ 否             | ✅ 是          |
| 非原始 JS 类型 | ❌ 否             | ✅ 是          |

## 外部配置文件

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

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

下面是其他常见配置文件的列表：

| 名称                                           | 配置文件                  | 如何配置                                                                     |
| -------------------------------------------- | --------------------- | ------------------------------------------------------------------------ |
| [TypeScript](https://www.typescriptlang.org) | `tsconfig.json`       | [更多信息](https://nuxt.zhcndoc.com/docs/4.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/)                                       |
| [Vite+](https://viteplus.dev)                | `vite.config.ts`      | [更多信息](https://viteplus.dev/config/)                                     |

如果使用 Vite+，其 `vite.config.ts` 用于配置 `vp lint`、`vp fmt` 和 `vp test` 等 Vite+ 命令。Nuxt 不会从该文件读取 Vite 选项，因此需要在 `nuxt.config` 中通过 [`vite`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#vite) 键配置应用的 Vite。

## 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/4.x/api/nuxt-config#vue"}
::

### 使用 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/4.x/api/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/4.x/api/nuxt-config#vue-1"}
::


## Sitemap

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