配置

默认情况下，Nuxt 的配置已涵盖大多数用例。nuxt.config.ts 文件可以覆盖或扩展此默认配置。

¥By default, Nuxt is configured to cover most use cases. The nuxt.config.ts file can override or extend this default configuration.

Nuxt 配置

¥Nuxt Configuration

nuxt.config.ts 文件位于 Nuxt 项目的根目录下，可以覆盖或扩展应用的行为。

¥The nuxt.config.ts file is located at the root of a Nuxt project and can override or extend the application's behavior.

一个最小的配置文件导出一个 defineNuxtConfig 函数，该函数包含一个包含你配置的对象。defineNuxtConfig 助手无需导入即可全局使用。

¥A minimal configuration file exports the defineNuxtConfig function containing an object with your configuration. The defineNuxtConfig helper is globally available without import.

export default defineNuxtConfig({
  // My Nuxt config
})

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

¥This file will often be mentioned in the documentation, for example to add custom scripts, register modules or change rendering modes.

:

每个选项都在配置参考中进行了描述。

¥Every option is described in the Configuration Reference.

::

环境变量覆盖

¥Environment Overrides

你可以在 nuxt.config 中配置完全类型化、每个环境的覆盖。

¥You can configure fully typed, per-environment overrides in your nuxt.config

export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true }
    }
  },
  $development: {
    //
  },
  $env: {
    staging: {
      // 
    }
  },
})

要在运行 Nuxt CLI 命令时选择环境，只需将名称传递给 --envName 标志，如下所示：nuxi build --envName staging。

¥To select an environment when running a Nuxt CLI command, simply pass the name to the --envName flag, like so: nuxi build --envName staging.

要了解更多关于这些覆盖机制的信息，请参阅 特定于环境的配置 上的 c12 文档。

¥To learn more about the mechanism behind these overrides, please refer to the c12 documentation on environment-specific configuration.

环境变量和私有令牌

¥Environment Variables and Private Tokens

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

¥The runtimeConfig API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within runtimeConfig.public and runtimeConfig.app (which is used by Nuxt internally) are also available client-side.

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

¥Those values should be defined in nuxt.config and can be overridden using environment variables.

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'
    }
  }
})

# This will override the value of apiSecret
NUXT_API_SECRET=api_secret_token

这些变量通过 useRuntimeConfig() 可组合项暴露给应用的其余部分。

¥These variables are exposed to the rest of your application using the useRuntimeConfig() composable.

<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>

应用配置

¥App Configuration

app.config.ts 文件位于源目录（默认为项目根目录），用于公开可在构建时确定的公共变量。与 runtimeConfig 选项相反，这些不能使用环境变量覆盖。

¥The app.config.ts file, located in the source directory (by default the root of the project), is used to expose public variables that can be determined at build time. Contrary to the runtimeConfig option, these can not be overridden using environment variables.

一个最小的配置文件导出一个 defineAppConfig 函数，该函数包含一个包含你配置的对象。defineAppConfig 助手无需导入即可全局使用。

¥A minimal configuration file exports the defineAppConfig function containing an object with your configuration. The defineAppConfig helper is globally available without import.

export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000'
    }
  }
})

这些变量通过 useAppConfig 可组合项暴露给应用的其余部分。

¥These variables are exposed to the rest of your application using the useAppConfig composable.

<script setup lang="ts">
const appConfig = useAppConfig()
</script>

runtimeConfig 与 app.config

¥runtimeConfig vs. app.config

如上所述，runtimeConfig 和 app.config 均用于向应用的其余部分公开变量。要确定是否应该使用其中一个，请遵循以下准则：

¥As stated above, runtimeConfig and app.config are both used to expose variables to the rest of your application. To determine whether you should use one or the other, here are some guidelines:

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

外部配置文件

¥External Configuration Files

Nuxt 使用 nuxt.config.ts 文件作为配置的唯一可信来源，并跳过读取外部配置文件。在构建项目的过程中，你可能需要配置这些。下表重点介绍了常用配置，以及在适用的情况下如何使用 Nuxt 配置它们。

¥Nuxt uses nuxt.config.ts file as the single source of truth for configurations and skips reading external configuration files. During the course of building your project, you may have a need to configure those. The following table highlights common configurations and, where applicable, how they can be configured with Nuxt.

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

¥Here is a list of other common config files:

Vue 配置

¥Vue Configuration

使用 Vite

¥With Vite

如果你需要将选项传递给 @vitejs/plugin-vue 或 @vitejs/plugin-vue-jsx，你可以在 nuxt.config 文件中执行此操作。

¥If you need to pass options to @vitejs/plugin-vue or @vitejs/plugin-vue-jsx, you can do this in your nuxt.config file.

• vite.vue 代表 @vitejs/plugin-vue。查看 此处 的可用选项。
• vite.vueJsx 代表 @vitejs/plugin-vue-jsx。查看 此处 的可用选项。

export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true
    },
    vueJsx: {
      mergeProps: true
    }
  }
})

使用 webpack

¥With webpack

如果你使用 webpack 并需要配置 vue-loader，你可以在 nuxt.config 文件中使用 webpack.loaders.vue 键来执行此操作。定义于此处 提供以下可用选项。

¥If you use webpack and need to configure vue-loader, you can do this using webpack.loaders.vue key inside your nuxt.config file. The available options are defined here.

export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      }
    }
  }
})

启用实验性 Vue 功能

¥Enabling Experimental Vue Features

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

¥You may need to enable experimental features in Vue, such as propsDestructure. Nuxt provides an easy way to do that in nuxt.config.ts, no matter which builder you are using:

export default defineNuxtConfig({
  vue: {
    propsDestructure: true
  }
})

从 Vue 3.4 和 Nuxt 3.9 进行实验性的 reactivityTransform 迁移

¥experimental reactivityTransform migration from Vue 3.4 and Nuxt 3.9

自 Nuxt 3.9 和 Vue 3.4 起，reactivityTransform 已从 Vue 移至包含 Nuxt 集成 的 Vue Macros。

¥Since Nuxt 3.9 and Vue 3.4, reactivityTransform has been moved from Vue to Vue Macros which has a Nuxt integration.