Nuxt3 中文课程《实战全栈开发简书》限时优惠

配置

Nuxt已经配置了合理的默认值,以提高你的生产效率。

默认情况下,Nuxt已经配置了大多数使用情况。nuxt.config.ts文件可以覆盖或扩展此默认配置。

Nuxt配置

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

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

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

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

每个选项在配置参考中都有详细描述。
你不必使用TypeScript来构建Nuxt应用程序。然而,强烈推荐使用.ts扩展名作为nuxt.config文件的扩展名。这样你可以在IDE中受益于提示,避免在编辑配置时出现拼写错误和其他错误。

环境覆盖

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

nuxt.config.ts
export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true }
    }
  },
  $development: {
    //
  }
})
如果你正在编写层,你也可以使用$meta键来提供你自己或你的层的使用者可能使用的元数据。

环境变量和私有令牌

runtimeConfig API将像环境变量这样的值暴露给应用程序的其余部分。默认情况下,这些键只在服务器端可用。runtimeConfig.public中的键也可以在客户端使用。

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

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

这些变量通过useRuntimeConfig()组合函数暴露给应用程序的其余部分。

pages/index.vue
<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>
Read more in 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>
Read more in Docs > Guide > Directory Structure > App Config.

runtimeConfigapp.config

如上所述,runtimeConfigapp.config都用于向应用程序的其余部分公开变量。为了确定应该使用其中之一,以下是一些指导原则:

  • runtimeConfig:需要在构建后使用环境变量指定的私有或公共令牌。
  • app.config:在构建时确定的公共令牌,网站配置(如主题变体、标题)以及不敏感的项目配置等。
功能runtimeConfigapp.config
客户端端已注入已打包
环境变量✅ 是❌ 否
响应式✅ 是✅ 是
类型支持✅ 部分✅ 是
每个请求的配置❌ 否✅ 是
热模块替换❌ 否✅ 是
非原始JS类型❌ 否✅ 是

外部配置文件

Nuxt使用nuxt.config.ts文件作为配置的唯一来源,并跳过读取外部配置文件。在构建项目的过程中,你可能需要配置这些文件。下表列出了常见的配置以及如何在Nuxt中配置它们(如果适用)。

名称配置文件如何配置
Nitronitro.config.tsnuxt.config中使用nitro
PostCSSpostcss.config.jsnuxt.config中使用postcss
Vitevite.config.tsnuxt.config中使用vite
webpackwebpack.config.tsnuxt.config中使用webpack

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

名称配置文件如何配置
TypeScripttsconfig.json更多信息
ESLint.eslintrc.js更多信息
Prettier.prettierrc.json更多信息
Stylelint.stylelintrc.json更多信息
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
    }
  }
})

详细内容请参阅:

Read more in 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,
      }
    }
  }
})

详细内容请参阅:

Read more in Docs > API > Configuration > Nuxt Config#loaders.

启用实验性 Vue 功能

你可能需要在 Vue 中启用实验性功能,例如 defineModelpropsDestructure。无论你使用哪个构建工具,Nuxt 都提供了一种简单的方法在 nuxt.config.ts 中进行配置:

nuxt.config.ts
export default defineNuxtConfig({
  vue: {
    defineModel: true,
    propsDestructure: true
  }
})

详细内容请参阅:

Read more in Docs > API > Configuration > Nuxt Config#vue 1.