配置 Configuration

Nuxt 配置了合理的默认值。 配置文件可以覆盖或扩展它们。

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

Nuxt配置

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

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

nuxt.config.ts
ts
export default defineNuxtConfig({
  // My Nuxt config
})

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

您不必使用 TypeScript 来构建带有 Nuxt 的应用程序。 但是，强烈建议对 nuxt.config 文件使用 .ts 扩展名。 通过这种方式，您可以从 IDE 中的提示中获益，以避免在编辑配置时出现错别字和错误。

相关阅读：配置参考

环境覆盖

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

nuxt.config.ts
ts
export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true }
    }
  },
  $development: {
    //
  }
})

如果您正在创作图层，您还可以使用$meta键来提供您或图层的使用者可能使用的元数据。

环境变量和私有令牌

runtimeConfigAPI 向应用程序的其余部分公开环境变量等值。

默认情况下，这些密钥仅在服务器端可用。runtimeConfig.public中的密钥也可在客户端使用。

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

ts
nuxt.config.ts
ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 仅在服务器端可用的私钥
    apiSecret: '123',
    // public 中的密钥也暴露在客户端
    public: {
      apiBase: '/api'
    }
  }
})

这些变量使用 useRuntimeConfig 可组合项暴露给应用程序的其余部分。

pages/index.vue
vue
<script setup>
const runtimeConfig = useRuntimeConfig()
</script>
相关阅读：docs > nuxtjs > going-further > runtime-config

应用配置

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

一个最小的配置文件导出包含一个对象的 defineAppConfig 函数和您的配置。 defineAppConfig 助手无需导入即可在全球范围内使用。

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

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

pages/index.vue
vue
<script setup>
const appConfig = useAppConfig()
</script>
相关阅读：docs > nuxtjs > dirs > app-config

runtimeConfig vs app.config

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

  • runtimeConfig：需要在使用环境变量构建后指定的私有或公共令牌。
  • app.config：在构建时确定的公共令牌、网站配置，例如主题变体、标题和任何不敏感的项目配置。
特性runtimeConfigapp.config
客户端：Client SideHydratedBundled
环境变量：Environment Variables✅ 是❌ 否
响应式：Reactive✅ 是✅ 是
类型支持：Types support✅ 部分✅ 是
每个请求的配置：Configuration per Request❌ 否✅ 是
热更新：Hot Module Replacement❌ 否✅ 是
非原始JS类型：Non primitive JS types❌ 否✅ 是

外部配置文件

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配置文档
ESLint.eslintrc.js配置文档
Prettier.prettierrc.json配置文档
Stylelint.stylelintrc.json配置文档
TailwindCSStailwind.config.js配置文档
Vitestvitest.config.ts配置文档

Vue Configuration

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
ts
export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true
    },
    vueJsx: {
      mergeProps: true
    }
  }
})
相关阅读：docs > nuxtjs > dirs > nuxt-config#vue

With webpack

如果您使用 webpack 并需要配置 vue-loader，您可以使用 nuxt.config 文件中的 webpack.loaders.vue 键来完成此操作。 可用选项在此处定义。

nuxt.config.ts
ts
export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      }
    }
  }
})
相关阅读：docs > nuxtjs > dirs > nuxt-config#loaders

启用实验性 Vue 功能

您可能需要在 Vue 中启用实验性功能，例如defineModel或propsDestruct。 Nuxt 在 nuxt.config.ts 中提供了一种简单的方法来做到这一点，无论您使用哪个构建器：

nuxt.config.ts
ts
export default defineNuxtConfig({
  vue: {
    defineModel: true,
    propsDestructure: true
  }
})
相关阅读：docs > nuxtjs > dirs > nuxt-config#vue