Nuxt 构建工具链迁移指南：从 Nuxt 2（webpack + Babel）迁移到新一代 Vite/webpack5 + esbuild 体系-优快云博客

Nuxt 构建工具链迁移指南：从 Nuxt 2（webpack + Babel）迁移到新一代 Vite/webpack5 + esbuild 体系

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

Nuxt 3 起对构建工具链进行了彻底重构：默认采用 Vite 或 webpack 5、Rollup、PostCSS、esbuild 组合，取代了 Nuxt 2 时代以 webpack 4 + Babel 为核心的构建体系，并内置了 TypeScript 支持。本文基于官方迁移指南 docs/7.migration/10.bundling.md，结合本仓库 schema 源码逐项说明哪些旧配置会被忽略、如何通过新的顶级配置键接管构建工具，以及完成迁移所需的清理步骤与注意事项，帮助读者平稳落地到全新的打包体系。

新构建体系概览：默认工具与职责分工

从 Nuxt 2 迁移到 Nuxt 3+，最直观的变化是底层打包技术栈整体换代。当前 Nuxt 默认使用以下构建工具：

Vite 或 webpack：负责应用代码的模块打包与开发服务器；
Rollup：用于服务端产物与依赖预打包（nitro 服务端构建的基础）；
PostCSS：负责 CSS 后处理（自动加前缀、压缩等）；
esbuild：提供极速的转译能力（TypeScript/JSX 剥离、压缩等）。

这一组合在仓库依赖层面有直接体现：根目录 package.json 的 devDependencies 中同时声明了 vite、webpack、rollup 三套工具链（catalog 管理版本），而 packages/vite、packages/webpack、packages/vite-server 等目录则承载了各构建器的实现逻辑。

配套的，Nuxt 3+ 原生内置 TypeScript 支持，无需再通过额外模块引入。这一变革的完整背景可参考迁移总览：技术栈从 Vue 2 到 Vue 3、从 webpack 4 + Babel 到 Vite/webpack 5 + esbuild，服务端也从运行时依赖 Nuxt 变为由 nitropack 编译的独立最小化 server。

旧 `build` 配置的废弃：哪些配置不再生效

由于上述工具链的更替，Nuxt 2 中绝大部分写在 build 键下的配置在新版本中会被直接忽略，其中最典型的是自定义 Babel 配置。

在 Nuxt 2 中，常见的 Babel 定制写法大致如下（迁移后无效）：

export default {
  build: {
    babel: {
      presets: ['@nuxt/babel-preset-app'],
      plugins: ['@babel/plugin-transform-runtime'],
    },
  },
}

新版本不再按此方式承载 Babel 选项：默认转译路径已由 esbuild 接管，Vite 构建器对 Vue SFC 的处理走 Vue 编译器内部逻辑（见下文对 vite.ts 的解析），不再暴露统一的 Babel 定制口子。

「需要配置构建工具时怎么办？」迁移指南给出的答案是：使用 nuxt.config 中新的顶层键 vite、webpack 和 postcss 分别接管对应工具。这三个键的默认值与解析逻辑均可在本仓库 packages/schema/src/config/ 下找到：

vite → vite.ts
webpack → webpack.ts
postcss → postcss.ts

注意：仓库中配置解析入口 config/index.ts 还暴露了 esbuild 与 build 等键，其中 build 仅保留 transpile、analyze 等少量跨构建器通用能力（详见下文），Babel 相关的语义已彻底移除。

构建器选择：默认 Vite，可切换 webpack

旧版本构建器的选择方式也随之变化。在 build.ts 中，builder 键会把字符串映射到对应的构建器包：

const map = {
  rspack: '@nuxt/rspack-builder',
  vite: '@nuxt/vite-builder',
  webpack: '@nuxt/webpack-builder',
}
// 未配置时默认返回 map.vite，即 @nuxt/vite-builder

也就是说，当前仓库默认使用 Vite；如需回到 webpack 语义，可显式声明 builder: 'webpack'（对应 @nuxt/webpack-builder），并配合顶层 webpack 键进行配置。这也解释了为什么 webpack.ts 仍保留了完整的分包命名、loader、extractCSS 等旧式选项——它们服务于选择 webpack 构建器时的用户。对应地，esbuild.ts 中 esbuild 的默认 target 会根据当前 builder 动态解析（Vite 下为 esnext，非 Vite 构建器且启用 decorators 实验特性时才降级到 es2024）。

保留的通用 `build` 能力

即便在 Nuxt 3+，build 键也并未被完全移除，只是范围大幅收窄。从 build.ts 的解析逻辑看，以下通用能力仍然保留且被内部默认值填充：

build.transpile：声明需要转译的依赖（支持字符串、正则或回调函数），例如 build: { transpile: ['some-dep'] }；
build.analyze：启用打包体积分析，默认输出 treemap 模板到 analyzeDir 下的 {name}.html；
optimization：面向 useState、useFetch、useAsyncData 等关键组合式函数的 tree-shaking 与异步转换优化（如对 defineNuxtPlugin、definePageMeta 的 asyncTransforms），其默认清单同样在 build.ts 中维护。

因此迁移时无需把旧 build 下的全部配置丢弃，但需甄别：与 Babel、webpack 4 loader 相关的部分应移除或迁移至顶层 vite/webpack 键。

Vite 顶层配置：默认值与常用定制点

vite 键透传给 Vite，同时 Nuxt 会注入一批默认值。从 vite.ts 的 resolver 可以看出几个值得注意的默认行为：

vite.define：自动注入 process.dev / import.meta.dev、process.test / import.meta.test、__VUE_OPTIONS_API__ 等编译期常量（值与 dev、test、debug 及 vue.optionsApi 联动）；
vite.resolve.extensions：默认在 JS 扩展名基础上追加 .vue、.json；
vite.publicDir：被强制固定为 false，并触发一条 schema 诊断——Nuxt 不希望用户自行配置 Vite 的 publicDir，静态资源统一交给 Nuxt 的 public/ 目录（这与目录结构文档中 public/ 目录的定位一致）；
vite.build.assetsDir：默认取自 app.buildAssetsDir（去掉前导 /），并设置 emptyOutDir: false 以保护产物目录；
vite.cacheDir：默认解析到 node_modules/.cache/vite（monorepo 场景下会考虑 workspace 布局）；
vite.server.fs.allow：自动合并 buildDir、srcDir、rootDir、workspaceDir 白名单，允许在开发服务器中访问这些目录。

示例：迁移后若需修改 Vite 的解析别名或关闭依赖预构建的某个排除项：

export default defineNuxtConfig({
  vite: {
    resolve: {
      alias: {
        '~my-lib': '/path/to/my-lib',
      },
    },
    optimizeDeps: {
      // 'vue-demi' 默认已被排除，这里再补充自定义排除项
      exclude: ['my-optional-dep'],
    },
  },
})

PostCSS 配置迁移：从 `build.postcss` 到顶层 `postcss`

Nuxt 2 中 PostCSS 配置位于 build.postcss 下，新版本则统一收口到顶层 postcss 键。其默认解析逻辑见 postcss.ts：

plugins 默认空对象，由用户按需声明（如 autoprefixer、cssnano）；
提供一个特殊的 order 选项，用于控制插件执行顺序。它支持三种形式：字符串预设名、函数或数组。内置预设包括 cssnanoLast（把 cssnano 排到最后）、autoprefixerLast（把 autoprefixer 排到最后）以及默认采用的 autoprefixerAndCssnanoLast（两者均排到最后，确保压缩与加前缀在管道末尾执行）。传入非法预设名时 resolver 会抛出 schema 诊断 NUXT_B5015。

迁移示例：

export default {
  build: {
    postcss: {
      plugins: {
        autoprefixer: {},
      },
    },
  },
}

export default defineNuxtConfig({
  postcss: {
    plugins: {
      autoprefixer: {},
      cssnano: {},
    },
    // 默认已保证 autoprefixer 与 cssnano 位于末尾，可按需覆盖
  },
})

渐进式迁移步骤（四步清理清单）

迁移指南为 Nuxt 2 项目升级到新构建体系给出了明确的四步操作，以下逐一展开说明：

1. 移除 `@nuxt/typescript-build` 与 `@nuxt/typescript-runtime`

Nuxt 3+ 原生内置 TypeScript 支持，构建器与运行期都已集成 TS 转译能力，无需再引入这两个 Nuxt 2 专用模块。请将它们从 package.json 的 dependencies 以及 nuxt.config 的 modules / buildModules 中一并删除。

关于新版本 TypeScript 集成方式的详细说明，可参阅仓库中的 TypeScript 概念指南（Nuxt 会自动生成类型、提供编辑器提示，并可通过 nuxi typecheck 配合 vue-tsc 做类型检查，详见迁移配置文档中 tsconfig 一节）。

2. 移除项目中不再使用的 Babel 依赖

既然默认转译路径已切换为 esbuild（及 Vite 内置转换），旧项目中为了兼容 webpack 4 引入的 @babel/* 系列依赖（如 @babel/core、@babel/preset-env、@babel/runtime 及各类 Babel 插件）均可移除。同时删除 nuxt.config 中已被忽略的 build.babel 配置，以及 .babelrc / babel.config.js 等文件（除非项目里仍有其他非 Nuxt 工具链在使用它们）。

3. 移除显式的 `core-js` 依赖

Nuxt 2 时代常需显式安装 core-js 并配置 polyfill 行为；新构建链默认输出面向现代浏览器的产物，并将 polyfill 决策交由构建器与目标环境处理，因此应从依赖中移除显式的 core-js 声明，避免与内置处理产生冲突。

4. 将 `require` 迁移为 `import`

新框架全面 ESM 化（相关概念参见 ESM 指南）。迁移时需把源码与配置中的 CJS 写法改为 ESM 写法：

// 迁移前（CommonJS）
const fs = require('node:fs')
const lib = require('my-lib')
module.exports = { ... }

// 迁移后（ESM）
import fs from 'node:fs'
import lib from 'my-lib'
export default { ... }

这一要求同样适用于 nuxt.config 文件本身：应使用 defineNuxtConfig + export default，并避免在其中使用 require / module.exports，详见迁移配置文档的 "ESM Syntax" 小节。

迁移前后配置对照速览

关注点	Nuxt 2（旧）	Nuxt 3+（新）	依据
应用打包	webpack 4 + Babel	Vite（默认）或 webpack 5 + esbuild	build.ts 默认 `builder: 'vite'`
Babel 配置	`build.babel`	已忽略，不再提供入口	docs/7.migration/10.bundling.md
构建器选项	`build.*`	顶层 `vite` / `webpack` / `postcss` 键	vite.ts
PostCSS	`build.postcss`	顶层 `postcss`	postcss.ts
TypeScript	`@nuxt/typescript-build` / `-runtime`	内建支持，配合 `nuxi typecheck`	TypeScript 指南
Polyfill	显式 `core-js`	移除显式依赖	本指南 Steps
模块语法	`require`	`import`（全面 ESM）	ESM 指南
通用转译	`build.transpile`（仍可用）	`build.transpile`（保留）	build.ts

迁移后的验证建议

完成上述清理后，建议依次执行以下验证以确认构建链路已完全切换到新体系：

删除 node_modules 中残留的 Babel / core-js / typescript-build 相关包并重新安装依赖；
运行开发服务器（nuxi dev），确认 Vite（或所选 webpack 构建器）能正常启动、热更新生效；
执行生产构建（nuxi build），确认 SSR 产物经由 Rollup/ nitro 正确产出，并检查 build.transpile 中声明的外部依赖是否被正确转译；
运行 nuxi typecheck（配合 vue-tsc）验证类型正确性，确认已无 @nuxt/typescript-* 运行期介入。

整个迁移的核心判断标准只有一个：旧的 build + Babel 心智模型彻底让位于 "顶层 vite/webpack/postcss 键 + 内建 TypeScript + ESM 优先" 的新模型。只要围绕新模型的配置键做定制、把上表列出的旧依赖与旧语法清理干净，即可顺利完成构建工具链的升级。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Nuxt 构建工具链迁移指南：从 Nuxt 2（webpack + Babel）迁移到新一代 Vite/webpack5 + esbuild 体系