Nuxt 4 配置指南：nuxt.config.ts、环境特定配置与 runtimeConfig / app.config 的分工

Nuxt 4 配置指南：nuxt.config.ts、环境特定配置与 runtimeConfig / app.config 的分工

【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt

本篇技术指南以 Nuxt 官方文档《Configuration》为主体，系统讲解 Nuxt 的三层配置体系：项目根目录的nuxt.config.ts（全局行为与环境覆盖）、可通过环境变量覆盖的runtimeConfig，以及构建期确定的app.config.ts。读完本文，你将掌握：如何用defineNuxtConfig覆盖默认配置、如何通过$production/$env.staging编写类型安全的环境特定配置并用--envName选择环境、如何安全地分发私密令牌与公开变量，以及为什么 Vite / webpack / Nitro / PostCSS 等外部配置文件不应单独存在——所有这些结论均可在 Nuxt 仓库源码中找到对应实现。

Nuxt 配置：nuxt.config.ts 是唯一的配置事实来源

Nuxt 以合理的默认值开箱即用，覆盖绝大多数使用场景。如需定制应用行为，唯一的入口是位于 Nuxt 项目根目录的nuxt.config.ts。它可以在不复制默认配置的前提下覆盖或扩展现有行为，并且会在文档中被频繁提及——例如添加自定义脚本、注册模块、切换渲染模式等。

最小化的配置文件只需导出defineNuxtConfig函数，其参数即你的配置对象。defineNuxtConfig是全局可用的辅助函数，无需手动 import：

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

仓库自带的 playground/nuxt.config.ts 就是一个真实的最小示例：

export default defineNuxtConfig({ devtools: { enabled: true }, compatibilityDate: 'latest', })

Nuxt 官方文档建议：虽然构建 Nuxt 应用并非必须使用 TypeScript，但强烈建议使用.ts扩展名编写nuxt.config文件，这样可以在 IDE 中获得自动补全与类型提示，避免拼写错误。完整的逐项配置参考见 Configuration Reference。

环境特定配置覆盖（Environment Overrides）

在nuxt.config中，可以通过以$开头的键声明完全类型化、按环境区分的配置覆盖。官方文档给出的完整示例如下：

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

• $production/$development：在 Nuxt 判定当前为生产或开发环境时自动生效；
• $env.<name>：按显式指定的环境名生效，适合 staging、preview 等自命名环境。

运行 Nuxt CLI 命令时，通过--envName标志选择环境即可，例如nuxt build --envName staging会加载$env.staging中的覆盖项。

从源码结构看，这套机制的落地路径非常清晰：

• packages/schema/src/config/common.ts 中定义了envName配置项：若未在配置中显式给出，则根据dev状态解析为'development'或'production'；
• packages/kit/src/loader/config.ts 中loadNuxtConfig接受envName参数，且注释明确指出 CLI 显式传入的envName（如nuxt --envName）优先于nuxt.config中设置的envName；同文件 L459-L462 实现了这一优先级合并逻辑；
• 解析后的环境名会暴露给运行时应用代码，packages/nuxt/src/app/types/augments.ts 为import.meta.envName声明了类型；
• 测试用例 packages/kit/test/load-nuxt-config.spec.ts 验证了loadNuxtConfig({ cwd, envName: 'staging' })后config.envName确实为'staging'。

该覆盖机制底层基于 unjs/c12 的“environment-specific configuration”实现。此外，如果你正在编写 layer（多应用/层结构），还可以使用$meta键提供供层作者或消费方使用的元数据。

runtimeConfig：环境变量与私密令牌

runtimeConfigAPI 将环境变量式的值暴露给应用其余部分。默认情况下，这些键仅服务端可用；而runtimeConfig.public与 Nuxt 内部使用的runtimeConfig.app中的键也会在客户端可用。

这些值应在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

即：runtimeConfig中的每个键都可以按NUXT_前缀 + 大写化 + 下划线替换的规则被同名环境变量覆盖（apiSecret→NUXT_API_SECRET）。更完整的机制说明见 Runtime Config 指南。

这些值在应用代码中通过useRuntimeConfig()composable 消费：

<!-- app/pages/index.vue --> <script setup lang="ts"> const runtimeConfig = useRuntimeConfig() </script>

App Configuration：app.config.ts

app.config.ts文件位于源目录（默认为app/），用于暴露构建期即可确定的公开变量。与runtimeConfig相反，这些变量不能通过环境变量覆盖。最小示例使用全局可用的defineAppConfig：

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

这些变量通过useAppConfigcomposable 暴露给应用：

<!-- app/pages/index.vue --> <script setup lang="ts"> const appConfig = useAppConfig() </script>

目录约定详见 app/app.config.ts 文档。

runtimeConfig vs. app.config：如何选择

两者都用于向应用暴露变量，官方给出的选型准则是：

• runtimeConfig：需要在构建之后通过环境变量指定的私密或公开令牌；
• app.config：构建期即确定的公开令牌，例如主题变体、网站标题等不敏感的站点配置。

官方特性对比表如下：

特性	runtimeConfig	app.config
Client-side	Hydrated（水合注入）	Bundled（打进包）
Environment variables	✅ 支持	❌ 不支持
Reactive	✅	✅
Types support	✅ Partial（部分）	✅
Configuration per request	❌	✅
Hot module replacement	❌	✅
Non-primitive JS types	❌	✅

注意两点差异的工程含义：runtimeConfig的值在客户端是随水合数据注入的，因此只支持原始类型且类型推导只是部分的；而app.config在构建时被打进客户端 bundle，天然支持 HMR、对象/函数等复杂类型以及按请求配置。

外部配置文件：为什么不写 vite.config.ts / postcss.config.js？

Nuxt 以nuxt.config.ts作为配置的唯一事实来源，跳过读取外部配置文件。构建过程中常见的几个外部配置需求，都可以改由nuxt.config中的对应键完成：

名称	外部配置文件	Nuxt 中的替代方式
Nitro	nitro.config.ts	使用nuxt.config中的nitro键
PostCSS	postcss.config.js	使用postcss键
Vite	vite.config.ts	使用vite键
webpack	webpack.config.ts	使用webpack键

这一行为不是口头约定，而是有代码强制保障的。packages/nuxt/src/core/external-config-files.ts 中的checkForExternalConfigurationFiles()会依次探测vite.config.*（含.js/.mjs/.ts/.cjs/.mts/.cts）、webpack.config.*（另含.coffee）、nitro.config.ts、postcss.config.js，一旦发现即触发诊断项NUXT_B5004（对应文档 docs/errors/b5004.md）提醒开发者；该检查由构建流程在 packages/nuxt/src/core/builder.ts 中调用。

此外，与构建工具链无关的常规配置文件仍保留在项目根目录，官方文档列出的清单为：

名称	配置文件	说明
TypeScript	tsconfig.json	见 tsconfig 目录约定文档
ESLint	eslint.config.js	按 ESLint 官方配置规范处理
Prettier	prettier.config.js	按 Prettier 官方配置方式处理
Stylelint	stylelint.config.js	按 Stylelint 官方配置方式处理
TailwindCSS	tailwind.config.js	由对应 Nuxt 模块接管
Vitest	vitest.config.ts	按 Vitest 官方配置方式处理

Vue 配置：vite.vue、webpack.loaders.vue 与 vue.propsDestructure

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 export default defineNuxtConfig({ vite: { vue: { customElement: true, }, vueJsx: { mergeProps: true, }, }, })

在 Vite 构建器中，viteConfig.vueJsx会被透传给 JSX 插件，见 packages/vite/src/vite.ts 中的VueJsxPlugin(nuxt, viteConfig.vueJsx)调用。

With webpack

如果使用 webpack 构建器，则通过webpack.loaders.vue键配置vue-loader：

// nuxt.config.ts export default defineNuxtConfig({ webpack: { loaders: { vue: { hotReload: true, }, }, }, })

启用 Vue 实验特性（与构建器无关）

无论使用哪个构建器，都可以在nuxt.config.ts顶层的vue键下启用 Vue 实验特性，例如propsDestructure：

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

从源码结构看，vue.propsDestructure是跨构建器共享的语义入口：Vite 侧在 packages/schema/src/config/vite.ts 中将其解析进@vitejs/plugin-vue的script.propsDestructure；webpack 侧在 packages/schema/src/config/webpack.ts 中通过$resolve回退到同一个vue.propsDestructure值。值得注意的是，packages/schema/src/config/app.ts 中propsDestructure的默认值已经是true，即当前仓库版本默认开启该实验特性；同文件还以同样的方式暴露了vue.vapor（Vue Vapor Mode，要求 Vue 3.6+）等实验开关。

reactivityTransform 的迁移说明

自 Nuxt 3.9 与 Vue 3.4 起，reactivityTransform已从 Vue 核心迁移至 Vue Macros 项目，Nuxt 场景下应改用其官方的 Nuxt 集成模块来启用响应式转换，而不再通过 Vue 核心选项配置。

小结

Nuxt 4 的配置模型可以归纳为三层：nuxt.config.ts负责全局行为、模块注册与环境覆盖（$production/$development/$env.<name>，配合--envName选择环境）；runtimeConfig负责可被环境变量覆盖的服务端/客户端变量，私密令牌永不泄漏到客户端；app.config.ts负责构建期确定的公开站点配置，享受完整类型推导与 HMR。而 Vite、webpack、Nitro、PostCSS 等构建工具的配置一律收口进nuxt.config的对应键，外部同名配置文件不仅不会被读取，还会在构建时触发NUXT_B5004诊断警告——这正是 external-config-files.ts 所保障的单一配置来源原则。

【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt