配置

Nuxt 开箱即用的合理配置让你高效开发。

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

Nuxt 配置

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

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

export default defineNuxtConfig({
  // 我的 Nuxt 配置
})

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

每个选项都在配置参考中有详细说明。

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

环境覆盖

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

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

运行 Nuxt CLI 命令时选择环境，只需把名字传给 --envName 参数，比如：nuxt build --envName staging。

想了解这些覆盖背后的机制，参考 c12 文档的环境特定配置。

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

环境变量和私有令牌

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

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

export default defineNuxtConfig({
  runtimeConfig: {
    // 只在服务端可用的私有键
    apiSecret: '123',
    // public 中的键在客户端也暴露
    public: {
      apiBase: '/api',
    },
  },
})

# 这会覆盖 apiSecret 的值
NUXT_API_SECRET=api_secret_token

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

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

应用配置

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

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

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

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

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

`runtimeConfig` vs. `app.config`

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

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

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

外部配置文件

Nuxt 使用 nuxt.config.ts 作为唯一配置源，不会读取外部配置文件。但在项目构建过程中，你可能需要配置这些。下表列出了常见配置以及在 Nuxt 中如何配置。

名称	配置文件	如何配置
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` 键

其他常见配置文件：

名称	配置文件	如何配置
TypeScript	`tsconfig.json`	更多信息
ESLint	`eslint.config.js`	更多信息
Prettier	`prettier.config.js`	更多信息
Stylelint	`stylelint.config.js`	更多信息
TailwindCSS	`tailwind.config.js`	更多信息
Vitest	`vitest.config.ts`	更多信息

Vue 配置

使用 Vite

如果你需要给 @vitejs/plugin-vue 或 @vitejs/plugin-vue-jsx 传选项，可以在 nuxt.config 文件中配置。

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

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

使用 webpack

如果你使用 webpack 并需要配置 vue-loader，可以在 nuxt.config 文件中使用 webpack.loaders.vue 键。可用选项在这里定义。

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

启用 Vue 实验性特性

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

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

experimental `reactivityTransform` 从 Vue 3.4 和 Nuxt 3.9 迁移

从 Nuxt 3.9 和 Vue 3.4 开始，reactivityTransform 已经从 Vue 移到 Vue Macros，它有 Nuxt 集成。

配置