配置

Nuxt 提供了合理的默认配置，让你高效开发。

默认情况下，Nuxt 已经配置好以覆盖大多数使用场景。nuxt.config.ts 文件可以覆盖或扩展这些默认配置。

Nuxt 配置（Nuxt Configuration）

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

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

nuxt.config.ts

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

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

每个选项都在配置参考中有详细描述。 :::

你并不一定要使用 TypeScript 来构建 Nuxt 应用。不过我们强烈建议为 nuxt.config 文件使用 .ts 扩展名。这样你可以在 IDE 中获得提示，避免在编辑配置时出现拼写错误。

环境覆盖（Environment Overrides）

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

nuxt.config.ts

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

要在运行 Nuxt CLI 命令时选择某个环境，只需将名称传给 --envName 参数，例如：nuxt build --envName staging。

要了解这些覆盖背后的机制，请参阅 c12 文档中关于特定环境配置的部分。

如果你在编写 layers，也可以使用 $meta 键来提供元数据，供你自己或该 layer 的使用者使用。

环境变量与私有令牌（Environment Variables and Private Tokens）

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

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

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() composable 暴露给应用其余部分。

app/pages/index.vue

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

应用配置（App Configuration）

app.config.ts 文件位于源代码目录（默认是 app/），用于暴露可在构建时确定的公共变量。与 runtimeConfig 选项不同，这些变量无法使用环境变量覆盖。

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

app/app.config.ts

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

这些变量通过 useAppConfig composable 暴露给应用其余部分。

app/pages/index.vue

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

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

如上所述，runtimeConfig 和 app.config 都用于向应用其余部分暴露变量。要判断该用哪个，可参考以下准则：

runtimeConfig：需要在构建后通过环境变量指定的私有或公共令牌。
app.config：在构建时确定的公共令牌，例如主题变体、标题以及任何不敏感的网站配置。

特性（Feature）	`runtimeConfig`	`app.config`
客户端可用（Client-side）	Hydrated	Bundled
环境变量（Environment variables）	✅ 是	❌ 否
响应式（Reactive）	✅ 是	✅ 是
类型支持（Types support）	✅ 部分	✅ 是
按请求配置（Configuration per request）	❌ 否	✅ 是
热模块替换（Hot module replacement）	❌ 否	✅ 是
非原始 JS 类型（Non-primitive JS types）	❌ 否	✅ 是

外部配置文件（External Configuration Files）

Nuxt 将 nuxt.config.ts 文件作为配置的唯一可信来源（single source of truth），并跳过读取外部配置文件。在构建项目的过程中，你可能需要配置这些外部文件。下表列出了常见配置，以及（如适用）如何在 Nuxt 中配置它们。

名称（Name）	配置文件（Config File）	配置方式（How To Configure）
Nitro	~~`nitro.config.ts`~~	在 `nuxt.config` 中使用 `nitro` 键
PostCSS	~~`postcss.config.js`~~	在 `nuxt.config` 中使用 `postcss` 键
Vite	~~`vite.config.ts`~~	在 `nuxt.config` 中使用 `vite` 键
webpack	~~`webpack.config.ts`~~	在 `nuxt.config` 中使用 `webpack` 键

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

名称（Name）	配置文件（Config File）	配置方式（How To Configure）
TypeScript	`tsconfig.json`	更多信息
ESLint	`eslint.config.js`	更多信息
Prettier	`prettier.config.js`	更多信息
Stylelint	`stylelint.config.js`	更多信息
TailwindCSS	`tailwind.config.js`	更多信息
Vitest	`vitest.config.ts`	更多信息

Vue 配置（Vue Configuration）

使用 Vite（With Vite）

如果你需要向 @vitejs/plugin-vue 或 @vitejs/plugin-vue-jsx 传递选项，可以在 nuxt.config 文件中完成。

vite.vue 对应 @vitejs/plugin-vue。查看可用选项。
vite.vueJsx 对应 @vitejs/plugin-vue-jsx。查看可用选项。

nuxt.config.ts

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

使用 webpack（With webpack）

如果你使用 webpack 并需要配置 vue-loader，可以在 nuxt.config 文件中使用 webpack.loaders.vue 键。可用选项参见此处。

nuxt.config.ts

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

{to="/docs/api/configuration/nuxt-config#loaders}

启用 Vue 实验性特性（Enabling Experimental Vue Features）

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

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 集成。

{to="/docs/api/configuration/nuxt-config#vue-1}