尧图网站建设 
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或productionpackages/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_SECRETapi_secret_token即runtimeConfig中的每个键都可以按NUXT_前缀 大写化 下划线替换的规则被同名环境变量覆盖apiSecret→NUXT_API_SECRET。更完整的机制说明见 Runtime Config 指南。这些值在应用代码中通过useRuntimeConfig()composable 消费!-- app/pages/index.vue -- script setup langts const runtimeConfig useRuntimeConfig() /scriptApp Configurationapp.config.tsapp.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 langts const appConfig useAppConfig() /script目录约定详见 app/app.config.ts 文档。runtimeConfig vs. app.config如何选择两者都用于向应用暴露变量官方给出的选型准则是runtimeConfig需要在构建之后通过环境变量指定的私密或公开令牌app.config构建期即确定的公开令牌例如主题变体、网站标题等不敏感的站点配置。官方特性对比表如下特性runtimeConfigapp.configClient-sideHydrated水合注入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.jsNuxt 以nuxt.config.ts作为配置的唯一事实来源跳过读取外部配置文件。构建过程中常见的几个外部配置需求都可以改由nuxt.config中的对应键完成名称外部配置文件Nuxt 中的替代方式Nitronitro.config.ts使用nuxt.config中的nitro键PostCSSpostcss.config.js使用postcss键Vitevite.config.ts使用vite键webpackwebpack.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 中调用。此外与构建工具链无关的常规配置文件仍保留在项目根目录官方文档列出的清单为名称配置文件说明TypeScripttsconfig.json见 tsconfig 目录约定文档ESLinteslint.config.js按 ESLint 官方配置规范处理Prettierprettier.config.js按 Prettier 官方配置方式处理Stylelintstylelint.config.js按 Stylelint 官方配置方式处理TailwindCSStailwind.config.js由对应 Nuxt 模块接管Vitestvitest.config.ts按 Vitest 官方配置方式处理Vue 配置vite.vue、webpack.loaders.vue 与 vue.propsDestructureWith 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.propsDestructurewebpack 侧在 packages/schema/src/config/webpack.ts 中通过$resolve回退到同一个vue.propsDestructure值。值得注意的是packages/schema/src/config/app.ts 中propsDestructure的默认值已经是true即当前仓库版本默认开启该实验特性同文件还以同样的方式暴露了vue.vaporVue 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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或productionpackages/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_SECRETapi_secret_token即runtimeConfig中的每个键都可以按NUXT_前缀 大写化 下划线替换的规则被同名环境变量覆盖apiSecret→NUXT_API_SECRET。更完整的机制说明见 Runtime Config 指南。这些值在应用代码中通过useRuntimeConfig()composable 消费!-- app/pages/index.vue -- script setup langts const runtimeConfig useRuntimeConfig() /scriptApp Configurationapp.config.tsapp.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 langts const appConfig useAppConfig() /script目录约定详见 app/app.config.ts 文档。runtimeConfig vs. app.config如何选择两者都用于向应用暴露变量官方给出的选型准则是runtimeConfig需要在构建之后通过环境变量指定的私密或公开令牌app.config构建期即确定的公开令牌例如主题变体、网站标题等不敏感的站点配置。官方特性对比表如下特性runtimeConfigapp.configClient-sideHydrated水合注入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.jsNuxt 以nuxt.config.ts作为配置的唯一事实来源跳过读取外部配置文件。构建过程中常见的几个外部配置需求都可以改由nuxt.config中的对应键完成名称外部配置文件Nuxt 中的替代方式Nitronitro.config.ts使用nuxt.config中的nitro键PostCSSpostcss.config.js使用postcss键Vitevite.config.ts使用vite键webpackwebpack.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 中调用。此外与构建工具链无关的常规配置文件仍保留在项目根目录官方文档列出的清单为名称配置文件说明TypeScripttsconfig.json见 tsconfig 目录约定文档ESLinteslint.config.js按 ESLint 官方配置规范处理Prettierprettier.config.js按 Prettier 官方配置方式处理Stylelintstylelint.config.js按 Stylelint 官方配置方式处理TailwindCSStailwind.config.js由对应 Nuxt 模块接管Vitestvitest.config.ts按 Vitest 官方配置方式处理Vue 配置vite.vue、webpack.loaders.vue 与 vue.propsDestructureWith 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.propsDestructurewebpack 侧在 packages/schema/src/config/webpack.ts 中通过$resolve回退到同一个vue.propsDestructure值。值得注意的是packages/schema/src/config/app.ts 中propsDestructure的默认值已经是true即当前仓库版本默认开启该实验特性同文件还以同样的方式暴露了vue.vaporVue 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考