---
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  // My Nuxt config
})
```

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

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/api/configuration/nuxt-config">

每个选项都在**配置参考**中进行了说明。

</read-more>

<note>

你不必使用 TypeScript 来构建 Nuxt 应用。然而，强烈建议对 `nuxt.config` 文件使用 `.ts` 扩展名。这样可以在 IDE 中获得提示，避免在编辑配置时出现拼写错误和其他错误。

</note>

### 环境覆盖

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

```ts [nuxt.config.ts]twoslash
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 的视频" video-id="DFZI2iVCrNc">



</video-accordion>

<note>

如果你正在编写 layer（层），也可以使用 `$meta` 键来提供你或使用你 layer 的消费者可能会使用的元数据。

</note>

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

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

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

<code-group>

```ts [nuxt.config.ts]twoslash
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
```

</code-group>

这些变量通过 [`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">



</read-more>

## 应用配置

位于源代码目录（默认 `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">



</read-more>

## `runtimeConfig` 与 `app.config`

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

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

<table>
<thead>
  <tr>
    <th>
      特性
    </th>
    
    <th>
      <code>
        runtimeConfig
      </code>
    </th>
    
    <th>
      <code>
        app.config
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      客户端
    </td>
    
    <td>
      已水合
    </td>
    
    <td>
      已打包
    </td>
  </tr>
  
  <tr>
    <td>
      环境变量
    </td>
    
    <td>
      ✅ 是
    </td>
    
    <td>
      ❌ 否
    </td>
  </tr>
  
  <tr>
    <td>
      响应式
    </td>
    
    <td>
      ✅ 是
    </td>
    
    <td>
      ✅ 是
    </td>
  </tr>
  
  <tr>
    <td>
      类型支持
    </td>
    
    <td>
      ✅ 部分
    </td>
    
    <td>
      ✅ 是
    </td>
  </tr>
  
  <tr>
    <td>
      按请求配置
    </td>
    
    <td>
      ❌ 否
    </td>
    
    <td>
      ✅ 是
    </td>
  </tr>
  
  <tr>
    <td>
      热模块替换
    </td>
    
    <td>
      ❌ 否
    </td>
    
    <td>
      ✅ 是
    </td>
  </tr>
  
  <tr>
    <td>
      非原始 JS 类型
    </td>
    
    <td>
      ❌ 否
    </td>
    
    <td>
      ✅ 是
    </td>
  </tr>
</tbody>
</table>

## 外部配置文件

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

<table>
<thead>
  <tr>
    <th>
      名称
    </th>
    
    <th>
      配置文件
    </th>
    
    <th>
      如何配置
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://nitro.build" rel="nofollow">
        Nitro
      </a>
    </td>
    
    <td>
      <del>
        <code>
          nitro.config.ts
        </code>
      </del>
    </td>
    
    <td>
      在 <code>
        nuxt.config
      </code>
      
       中使用 <a href="https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#nitro">
        <code>
          nitro
        </code>
      </a>
      
       键
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://postcss.org" rel="nofollow">
        PostCSS
      </a>
    </td>
    
    <td>
      <del>
        <code>
          postcss.config.js
        </code>
      </del>
    </td>
    
    <td>
      在 <code>
        nuxt.config
      </code>
      
       中使用 <a href="https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#postcss">
        <code>
          postcss
        </code>
      </a>
      
       键
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://vite.dev" rel="nofollow">
        Vite
      </a>
    </td>
    
    <td>
      <del>
        <code>
          vite.config.ts
        </code>
      </del>
    </td>
    
    <td>
      在 <code>
        nuxt.config
      </code>
      
       中使用 <a href="https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#vite">
        <code>
          vite
        </code>
      </a>
      
       键
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://webpack.js.org" rel="nofollow">
        webpack
      </a>
    </td>
    
    <td>
      <del>
        <code>
          webpack.config.ts
        </code>
      </del>
    </td>
    
    <td>
      在 <code>
        nuxt.config
      </code>
      
       中使用 <a href="https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#webpack-1">
        <code>
          webpack
        </code>
      </a>
      
       键
    </td>
  </tr>
</tbody>
</table>

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

<table>
<thead>
  <tr>
    <th>
      名称
    </th>
    
    <th>
      配置文件
    </th>
    
    <th>
      如何配置
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://www.typescriptlang.org" rel="nofollow">
        TypeScript
      </a>
    </td>
    
    <td>
      <code>
        tsconfig.json
      </code>
    </td>
    
    <td>
      <a href="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig">
        更多信息
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://eslint.org" rel="nofollow">
        ESLint
      </a>
    </td>
    
    <td>
      <code>
        eslint.config.js
      </code>
    </td>
    
    <td>
      <a href="https://eslint.org/docs/latest/use/configure/configuration-files" rel="nofollow">
        更多信息
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://prettier.io" rel="nofollow">
        Prettier
      </a>
    </td>
    
    <td>
      <code>
        prettier.config.js
      </code>
    </td>
    
    <td>
      <a href="https://prettier.io/docs/configuration.html" rel="nofollow">
        更多信息
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://stylelint.io" rel="nofollow">
        Stylelint
      </a>
    </td>
    
    <td>
      <code>
        stylelint.config.js
      </code>
    </td>
    
    <td>
      <a href="https://stylelint.io/user-guide/configure/" rel="nofollow">
        更多信息
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://tailwindcss.com" rel="nofollow">
        TailwindCSS
      </a>
    </td>
    
    <td>
      <code>
        tailwind.config.js
      </code>
    </td>
    
    <td>
      <a href="https://tailwindcss.nuxtjs.org/tailwindcss/configuration/" rel="nofollow">
        更多信息
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://vitest.dev" rel="nofollow">
        Vitest
      </a>
    </td>
    
    <td>
      <code>
        vitest.config.ts
      </code>
    </td>
    
    <td>
      <a href="https://vitest.dev/config/" rel="nofollow">
        更多信息
      </a>
    </td>
  </tr>
</tbody>
</table>

## 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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
    vueJsx: {
      mergeProps: true,
    },
  },
})
```

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/api/configuration/nuxt-config#vue">



</read-more>

### 使用 webpack

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

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

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/api/configuration/nuxt-config#loaders">



</read-more>

### 启用 Vue 的实验性特性

你可能需要启用 Vue 的实验性特性，例如 `propsDestructure`。无论使用哪种构建器，Nuxt 都提供了在 `nuxt.config.ts` 中轻松进行此操作的方法：

```ts [nuxt.config.ts]twoslash
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/configuration/nuxt-config#vue-1">



</read-more>


## Sitemap

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