Vue CLI 从 v4 迁移到 v5：完整升级指南与破坏性变更解析

Vue CLI 从 v4 迁移到 v5完整升级指南与破坏性变更解析【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli本文基于 Vue CLI 官方迁移文档 docs/migrations/migrate-from-v4.md 编写并结合当前仓库源码packages/vue/cli、packages/vue/cli-service及各插件包补充底层实现细节帮助你安全、平滑地完成从 Vue CLI 4 到 5 的升级并透彻理解每个破坏性变更背后的原因。快速上手两种升级路径从 v4 迁移到 v5 的第一步是先把全局的 CLI 工具本身升级到最新版本# 使用 npm npm install -g vue/cli # 使用 yarn yarn global add vue/cli升级完成后进入你的项目目录接下来有两种迁移策略可选路径一一键升级所有插件在既有项目中直接运行vue upgrade命令会扫描项目package.json中所有 Vue CLI 相关依赖vue/cli-service以及所有vue/cli-plugin-*、vue-cli-plugin-*插件列出可升级清单并询问是否继续随后按顺序逐个升级并自动执行对应的 migrator。你只需要跟随命令行提示即可完成整个过程。注意migrator 目前并未覆盖所有迁移场景vue upgrade之后仍建议完整阅读下文「破坏性变更」一节逐项核对你的自定义配置。路径二逐个手动升级如果希望逐步、可控地迁移可以指定插件名单独升级vue upgrade vue/cli-plugin-babel这种渐进式迁移方式适合插件较多、自定义较深的项目可以在每个插件升级后立即回归验证。升级失败提示清理锁文件与依赖如果你在升级后遇到类似下面的错误setup compilation vue-loader-plugin(node:44156) UnhandledPromiseRejectionWarning: TypeError: The compilation argument must be an instance of Compilation请删除项目中的锁文件yarn.lock或package-lock.json以及node_modules目录然后重新安装全部依赖即可解决。这通常是因为旧版依赖缓存与 webpack 5 的编译模型不兼容所致。深入理解vue upgrade的底层机制为了更自信地使用这条命令值得了解一下它的实现源码见 packages/vue/cli/lib/Upgrader.js依赖范围识别getUpgradable会遍历dependencies、devDependencies、optionalDependencies三类字段只关心vue/cli-service与符合isPlugin判断的插件包。升级顺序vue/cli-service会被强制排在清单首位upgradable.unshift因为它是其余所有插件的基础。版本解析默认目标是latest版本如果当前安装版本低于远程最新版本即进入升级流程。升级时安装的是包名~目标版本波浪号范围。migrator 自动执行升级完成后Upgrader 会尝试解析包名/migrator入口如vue/cli-plugin-babel/migrator。若存在则以子进程方式运行vue migrate 包名 --from 已安装版本见 packages/vue/cli/lib/upgrade.js 与 packages/vue/cli/lib/migrate.jsMigrator 会自动改写package.json、更新配置文件、必要时安装额外依赖并列出所有被修改/新增的文件提示你用git diff审阅后提交。git 状态检查升级前会先通过confirmIfGitDirty确认工作区是否干净避免升级过程与未提交的改动冲突。此外vue upgrade还支持几个实用选项--from 版本用于强制指定当前安装版本当依赖未安装时有用、--to 版本指定目标版本需同时给出包名、--next允许升级到 next 预发布版本、--all跳过交互确认直接升级全部。不带包名执行vue upgrade时会先打印一张包含Name / Installed / Wanted / Latest / Command to upgrade五列的概览表见Upgrader.checkForUpdates确认后再批量执行。破坏性变更总览以下变更按包维度组织请结合自己的项目逐项核对。所有包共有的变更Node.js 运行时要求不再支持 Node.js 8、9、10、11 与 13。从vue/cli-service的package.json可以看到引擎约束为node: ^12.0.0 || 14.0.0请确保本地 Node 版本满足要求。npm 5 不再支持请使用 npm 6 或 yarn。vue命令全局vue/cli包即时原型开发instant prototyping功能被移除。在 v4 中vue serve/vue build可以直接编译单个.vue文件到了 v5这两个命令只是npm run serve/npm run build的别名实际执行的是项目package.json中scripts字段定义的命令。如果你仍需要为独立的.vue组件搭建最小开发环境官方建议改用 https://sfc.vuejs.org/ 或 https://vite.new/vue 这类在线/本地单文件工具社区方案不属于本仓库功能。vue/cli-serviceWebpack 5v5 将底层 webpack 升级到了 5.xvue/cli-service的依赖中为webpack: ^5.54.0除了对自定义配置有大量内部变化外用户代码层面有两点值得特别注意JSON 模块的具名导出不再可用。此前可以这样写import { version } from ./package.json console.log(version)现在必须改为默认导出再取属性import package from ./package.json console.log(package.version)Node.js 模块的 polyfill 默认不再自动注入。如果你的代码依赖crypto、path、stream等 Node 内置模块webpack 5 会给出明确的报错提示需要自行安装并配置对应的 polyfill 方案。Dev Serverwebpack-dev-server v3 → v4devServer配置项在vue.config.js中有多处破坏性变更最值得注意的是disableHostCheck选项被移除改用allowedHosts: all达到相同效果public、sockHost、sockPath、sockPort四个选项被移除统一收敛为client.webSocketURL选项开发服务器的 IE9 支持不再默认启用。若仍需在 IE9 下开发调试请手动把devServer.webSocketServer设置为sockjs。vue/cli-service的依赖中webpack-dev-server为^4.7.3如果你在vue.config.js中深度定制过 devServer建议对照 webpack-dev-server 的 v4 迁移指南逐项检查。build命令与现代模式Modern Mode自 v5.0.0-beta.0 起vue-cli-service build会根据browserslist配置自动生成差异化产物--modern标志不再需要——因为它已经默认开启。从源码packages/vue/cli-service/lib/commands/build/index.js可以看到build命令的默认选项是{ clean: true, target: app, module: true, ... }即默认module: true随后通过allProjectTargetsSupportModule判断目标浏览器是否全部支持 ES Module若全部支持则跳过差异化构建。只有需要差异化时才设置VUE_CLI_MODERN_MODE先以主进程构建 legacy 包再以子进程VUE_CLI_MODERN_BUILD: true构建 modern 包最终产出script typemodule与script nomodule双份产物。具体行为取决于你的 browserslist 配置Vue 2 项目默认目标 1%, last 2 versions, not dead会产出两套包——面向支持script typemodule的现代浏览器app.[contenthash].js与chunk-vendors.[contenthash].js由于省去了针对旧浏览器的 polyfill 和转换体积明显更小面向不支持 module 的旧浏览器app-legacy.[contenthash].js与chunk-vendors-legacy.[contenthash].js通过script nomodule加载。关闭差异化构建追加--no-module标志即可vue-cli-service build --no-module只输出面向全部目标浏览器的 legacy 包通过普通script加载。Vue 3 项目默认目标 1%, last 2 versions, not dead, not ie 11所有目标浏览器都支持script typemodule没有区分必要因此vue-cli-service build只生成一套产物app.[contenthash].js与chunk-vendors.[contenthash].js普通script加载。build命令还保留了--mode、--dest、--target、--inline-vue、--formats、--name、--filename、--no-clean、--report、--report-json、--skip-plugins、--watch、--stdin等选项用法与 v4 一致。CSS Modulescss.requireModuleExtension选项被移除。如果你确实需要去掉 CSS Module 文件名中的.module部分请参考 docs/guide/css.md#css-modules 的指导例如自定义css.loaderOptions.css.modules与oneOf规则。底层css-loader从 v3 升级到 v6vue/cli-service依赖为css-loader: ^6.5.0一批与 CSS Modules 相关的选项被重命名。从 packages/vue/cli-service/lib/config/css.js 可以看到.module.文件与.vue内style module块分别由normal-modules与vue-modules规则处理自定义时注意与 v6 的配置结构对齐。Sass/SCSS不再支持用node-sass创建项目。node-sass所依赖的 libsass 已被官方弃用请改用sass包dart-sass。已有项目若使用node-sass建议迁移到sass并验证编译结果。Asset Modules资源模块url-loader与file-loader被移除取而代之的是 webpack 5 内置的 Asset Modules。如果你想调整图片等资源内联为 base64 的体积阈值现在需要配置Rule.parser.dataUrlCondition.maxSize// vue.config.js module.exports { chainWebpack: config { config.module .rule(images) .set(parser, { dataUrlCondition: { maxSize: 4 * 1024 // 4KiB } }) } }底层 Loader 与插件升级一览html-webpack-pluginv3 → v5vue/cli-service依赖为^5.1.0模板与chunksSortMode等行为有变化sass-loader放弃 v7 支持请使用 v8postcss-loaderv3 → v5依赖为^6.1.1最显著的变化是plugin/syntax/parser/stringifier等 PostCSS 选项被统一移入postcssOptions字段copy-webpack-pluginv5 → v8依赖为^9.0.1。如果你从未通过config.plugin(copy)定制过它基本无感terser-webpack-pluginv2 → v5依赖为^5.1.1基于 terser 5部分选项格式有变化新建项目时默认样式链路的版本整体上调less-loaderv5 → v8、lessv3 → v4、sass-loaderv8 → v11、stylus-loaderv3 → v5mini-css-extract-pluginv1 → v2依赖为^2.5.3cache-loader被移除如需使用请自行安装它在vue/cli-service中仍作为可选 peer 依赖保留便于旧项目平滑过渡。Babel 插件vue/cli-plugin-babeltranspileDependencies选项详见 docs/config/index.md#transpiledependencies现在接受布尔值设为true时将转译node_modules中的所有依赖保持数组形式时仍可精确指定要转译的包名或正则。从源码packages/vue/cli-plugin-babel/index.js可以看到transpileDependencies true时 babel-loader 的 exclude 逻辑会改为「除少数不可转译依赖如core-js、webpack、css-loader、mini-css-extract-plugin、html-webpack-plugin、whatwg-fetch等外全部转译」。该插件自带的 migratorpackages/vue/cli-plugin-babel/migrator/index.js还会用 codemod 改写babel.config.js并在从 v3 升级时把core-js提升到^3.8.3、提示核对自定义 polyfill 名称。ESLint 插件vue/cli-plugin-eslinteslint-loader被eslint-webpack-plugin取代因此放弃了对 ESLint ≤ 6 的支持新项目默认生成eslint-plugin-vuev8 配置注意其 v7/v8 的规则破坏性变更如果你使用vue/eslint-config-prettier请迁移到eslint-plugin-prettier方案。该插件的 migratorpackages/vue/cli-plugin-eslint/migrator/index.js会检测本地 ESLint 主版本号若为 v3/v4 早期项目eslint内置于插件内则补充eslint、babel/eslint-parser、eslint-plugin-vue依赖若 ESLint ≤ 6则自动升级到 v7 并把babel-eslint替换为babel/eslint-parserTypeScript 项目对应typescript-eslint/parser。PWA 插件vue/cli-plugin-pwa底层workbox-webpack-plugin从 v4 升级到 v6。如果项目深度定制了 workbox 配置请依次对照 v4→v5、v5→v6 的迁移指南调整。TypeScript 插件vue/cli-plugin-typescript放弃 TSLint 支持由于 TSLint 已被官方弃用v5 中所有 TSLint 相关代码被移除。请改用 ESLint可以使用tslint-to-eslint-config完成大部分自动化迁移。ts-loader从 v6 升级到 v9现在只支持 TypeScript 3.6fork-ts-checker-webpack-plugin从 v3.x 升级到 v6.x注意其 v4/v5/v6 的破坏性变更。该插件的 migratorpackages/vue/cli-plugin-typescript/migrator/index.js会统一typescript的 devDependency 版本并在 Vue 3 项目中对src/shims-vue.d.ts执行migrateComponentTypecodemod见 packages/vue/cli-plugin-typescript/codemods/migrateComponentType.js把Vue.extend风格的组件类型声明改写为 Vue 3 的组合式 API 类型。E2E-Cypress 插件vue/cli-plugin-e2e-cypressCypress 现在作为 peer dependency 要求项目需显式安装 Cypressmigrator 会在缺失时自动写入 devDependencies见 packages/vue/cli-plugin-e2e-cypress/migrator/index.jsCypress 从 v3 升级到 v8请参考 Cypress 官方迁移指南处理测试代码兼容问题。E2E-WebDriverIO 插件vue/cli-plugin-e2e-webdriverioWebDriverIO 从 v6 升级到 v7。对用户层面的破坏性变更不多但若使用自定义 WDIO 服务或报告器仍需核对 v7 的发布说明。E2E-Nightwatch 插件vue/cli-plugin-e2e-nightwatchNightwatch 从 v1 升级到 v2。除官方 v2 迁移指南外注意nightwatch.conf.js中globals、custom_commands等字段的组织方式变化。Unit-Jest 插件vue/cli-plugin-unit-jestVue 2 项目vue/vue2-jest现在是 peer dependency需要手动把vue/vue2-jest安装为项目的 devDependencyTypeScript 项目ts-jest现在是 peer dependency需要手动在项目根目录安装ts-jest27底层 jest 相关包从 v24 升级到 v27jest、babel-jest、ts-jest各有对应 changelog对大多数用户而言迁移是无感的。migratorpackages/vue/cli-plugin-unit-jest/migrator/index.js会自动补齐jest^27.1.0并按 Vue 版本写入vue/vue2-jest或vue/vue3-jest有 TypeScript 时补上ts-jest^27.0.4。Unit-Mocha 插件vue/cli-plugin-unit-mochamocha从 v6 升级到 v8注意 v7 起的破坏性变更如回调式done行为、全局--exit语义等jsdom从 v15 升级到 v18v16 起用户可见的破坏性变更如window相关 API 的收窄需要关注。内部包Internal Packagesvue/cli-shared-utilschalk从 v2 升级到 v4joi从 v15原hapi/joi升级到 v17。这两个主要影响插件开发者的依赖版本约束普通项目无感。迁移后的自检清单完成升级后建议按以下顺序做一轮收尾验证确认 Node 版本满足^12.0.0 || 14.0.0以 packages/vue/cli-service/package.json 的 engines 为准。检查 git 工作区升级前确保工作区干净升级后用git diff审阅 migrator 改动的package.json、babel.config.js、eslint配置、tsconfig等文件再提交。核对 browserslist确认.browserslistrc/package.json#browserslist是否仍然符合你的浏览器支持策略这直接影响 build 产物形态modern/legacy 双包还是单包。验证开发服务器若在vue.config.js中配置过devServer.disableHostCheck、public、sockHost等需按新的allowedHosts、client.webSocketURL语法改写。验证生产构建跑一次npm run build确认产物命名app.[contenthash].js/app-legacy.[contenthash].js等与预期一致检查图片内联阈值是否符合预期dataUrlCondition.maxSize。跑一遍测试与 E2E确认 Jest/Mocha、Cypress/Nightwatch/WDIO 升级后测试套件全部通过缺失的 peer dependency如vue/vue2-jest、ts-jest、cypress已显式安装。迁移过程的辅助源码索引升级命令核心实现packages/vue/cli/lib/Upgrader.js、packages/vue/cli/lib/upgrade.jsMigrator 运行管线packages/vue/cli/lib/migrate.js、packages/vue/cli/lib/Migrator.jsbuild命令与现代模式packages/vue/cli-service/lib/commands/build/index.jsCSS Modules 规则packages/vue/cli-service/lib/config/css.jsBabel 转译与transpileDependenciespackages/vue/cli-plugin-babel/index.js各插件 migratorpackages/vue/cli-plugin-babel/migrator/index.js、packages/vue/cli-plugin-eslint/migrator/index.js、packages/vue/cli-plugin-typescript/migrator/index.js、packages/vue/cli-plugin-unit-jest/migrator/index.js、packages/vue/cli-plugin-e2e-cypress/migrator/index.jsvue/cli-service依赖版本清单packages/vue/cli-service/package.json总之从 Vue CLI 4 迁移到 5 的核心工作可以概括为三件事升级全局 CLI、执行vue upgrade让 migrator 自动处理常规改动、再按本文的破坏性变更清单核对自定义配置。把 webpack 5、modern mode 与各插件的版本跃迁当作一次重构机会仔细回归测试迁移过程会远比想象中平滑。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考