[译]Nuxt 3 入门指南 - 配置 ｜ 青训营笔记

这是我参与「第五届青训营」伴学笔记创作活动的第 14 天。

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

Nuxt 配置

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

最小配置文件将导出包含具有您的配置的对象的 defineNuxtConfig 函数。辅助函数 defineNuxtConfig 无需导入即可全局使用。

// nuxt.config.ts

export default defineNuxtConfig({
    // My Nuxt config
})

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

配置API详情中介绍了每个配置选项。

使用 Nuxt 构建应用程序时，您不必非得使用 TypeScript。但是，强烈建议对 nuxt.config 文件使用 .ts 扩展名。这样，您就可以从 IDE 中的提示中受益，从而避免在编辑配置时出现拼写错误或是其他失误。

环境变量和非公开令牌

runtimeConfig 将环境变量之类的值公开给应用程序的其余部分。默认情况下，这些密钥仅在服务器端可用。在客户端也可以使用 runtimeConfig.public 中的密钥。

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

// nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available server-side
    apiSecret: '123',
    // Keys within public are also exposed client-side
    public: {
      apiBase: '/api'
    }
  }
})

# .env

# This will override the value of apiSecret
NUXT_API_SECRET=api_secret_token

这些变量会对应用程序中使用了 useRuntimeConfig 的 Composable 公开。

<script setup>
const runtimeConfig = useRuntimeConfig()
</script>

在文档 > 指南 > 更进一步 > 运行时配置中阅读更多内容。

App 配置

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

最小配置文件将导出包含具有您的配置的对象的 defineAppConfig 函数。辅助函数 runtimeConfig 无需导入即可全局使用。

// app.config.ts

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

这些变量会对应用程序中使用了 useAppConfig 的 Composable 公开。

<script setup>
const appConfig = useAppConfig()
</script>

在文档 > 指南 > 更进一步 > App 配置中阅读更多内容。

runtimeConfig 对比 app.config

如上所述，runtimeConfig 和 app.config 都用于向应用程序的其余部分公开变量。为了确定你应该使用哪一种，这里有一些指导原则：

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

特性	runtimeConfig	app.config
客户端	脱水/注水	打包
环境变量	✅ 是	❌ 否
支持响应式	✅ 是	✅ 是
支持类型系统	✅ 部分	✅ 是
一请求一配置	❌ 否	✅ 是
模块热替换（HMR）	❌ 否	✅ 是
支持非原生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	.eslintrc.js	更多细节
Prettier	.prettierrc.json	更多细节
Stylelint	.stylelintrc.json	更多细节
TailwindCSS	tailwind.config.js	更多细节
Vitest	vitest.config.ts	更多细节