配置

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

Nuxt 配置

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

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

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

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

环境覆盖配置

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

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

运行 Nuxt CLI 命令时，通过 --envName 参数指定环境，例如：nuxt build --envName staging。

有关此覆盖机制的更多信息，请参阅 c12 文档中的环境特定配置。

环境变量和私有令牌

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

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

应用配置

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

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

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

通过 useAppConfig 组合式 API 将这些变量暴露给应用其余部分。

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

runtimeConfig 与 app.config 区别

如前所述，runtimeConfig 和 app.config 都用于向应用其余部分暴露变量。选择使用哪一个，参考以下准则：

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

外部配置文件

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

其他常见配置文件清单：

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

Vue 3.4 与 Nuxt 3.9 中实验性 reactivityTransform 迁移

自 Nuxt 3.9 和 Vue 3.4 起，reactivityTransform 已从 Vue 移至 Vue Macros，并提供了 Nuxt 集成。