v4 (4.0.0)
Nuxt on GitHub

配置

Nuxt 默认采用合理的配置以提高开发效率。

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

Nuxt 配置

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

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

nuxt.config.ts
export default defineNuxtConfig({
  // 我的 Nuxt 配置
})

文档中会频繁提及此文件，例如添加自定义脚本、注册模块或更改渲染模式时。

所有选项详见配置参考。
使用 Nuxt 构建应用不强制要求 TypeScript。但强烈建议为 nuxt.config 文件使用 .ts 扩展名，这样可在 IDE 中获得提示，避免编辑配置时的拼写错误。

环境覆盖配置

你可以在 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 键来提供元数据，供你自己或层的使用者使用。

环境变量与私有令牌

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

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

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

使用 useRuntimeConfig() 组合式函数将这些变量暴露给应用其他部分。

pages/index.vue
<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>
阅读更多 Docs > Guide > Going Further > Runtime Config.

应用配置

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

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

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

使用 useAppConfig 组合式函数将这些变量暴露给应用其他部分。

pages/index.vue
<script setup lang="ts">
const appConfig = useAppConfig()
</script>
阅读更多 Docs > Guide > Directory Structure > App Config.

runtimeConfig 与 app.config 对比

如上所述，runtimeConfig 和 app.config 都用于向应用其他部分暴露变量。以下是选择使用哪个的指南：

  • runtimeConfig：需要在构建后通过环境变量指定的私有或公共令牌。
  • app.config：构建时确定的公共令牌，如主题变体、标题等非敏感项目配置。
功能runtimeConfigapp.config
客户端水合打包
环境变量✅ 支持❌ 不支持
响应式✅ 支持✅ 支持
类型支持✅ 部分✅ 支持
按请求配置❌ 不支持✅ 支持
热模块替换❌ 不支持✅ 支持
非原始 JS 类型❌ 不支持✅ 支持

外部配置文件

Nuxt 将 nuxt.config.ts 文件作为配置的唯一真实来源，跳过读取外部配置文件。在构建项目过程中，你可能需要配置这些文件。下表列出了常见配置及其在 Nuxt 中的配置方式。

名称配置文件如何配置
Nitronitro.config.ts在 nuxt.config 中使用 nitro 键
PostCSSpostcss.config.js在 nuxt.config 中使用 postcss 键
Vitevite.config.ts在 nuxt.config 中使用 vite 键
webpackwebpack.config.ts在 nuxt.config 中使用 webpack 键

其他常见配置文件列表：

名称配置文件如何配置
TypeScripttsconfig.json更多信息
ESLinteslint.config.js更多信息
Prettierprettier.config.js更多信息
Stylelintstylelint.config.js更多信息
TailwindCSStailwind.config.js更多信息
Vitestvitest.config.ts更多信息

Vue 配置

使用 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
    }
  }
})
阅读更多 Docs > API > Configuration > Nuxt Config#vue.

使用 webpack

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

nuxt.config.ts
export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      }
    }
  }
})
阅读更多 Docs > API > Configuration > Nuxt Config#loaders.

启用 Vue 实验性功能

你可能需要启用 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 集成。

阅读更多 Docs > API > Configuration > Nuxt Config#vue 1.