前言


当前只有Vue CLI英文网有迁移指南

对应的访问链接:Migrating from v3

目前中文网上暂时没有对应的中文文档。

为了方便一些小伙伴阅读,我翻译了下。

有些翻译是结合个人理解来翻译的,

有不对之处请留言,会及时修正,谢谢!


从v3迁移

首先全局安装最新的 vue-cli

npm install -g @vue/cli
# 或
yarn global add @vue/cli



一次升级所有插件

在你现有的项目,执行

vue upgrade


然后请参阅下面的部分,了解每个包中引入的破坏性变更(重大变更)。


逐步手动迁移

如果你想逐个手动迁移,这里有一些提示可以参考:


全局@vue/cli 

重新设计  vue upgrade 


vue --version 输出格式变动

当你执行 vue --version :


避免覆盖的额外确认(二次确认)

当你执行 vue invoke / vue add / vue upgrade,

如果当前项目下还有未提交的改动则会触发额外的确认步骤 


image.png


Vue路由及Vuex现也有对应的CLI插件

当你执行 vue add vuex 或 vue add router:


当前方案对最终用户并没有实际的影响,但这种设计允许我们以后可以为用户的Vuex和Vue路由器添加更多功能。


对于预设和插件的作者,对这两个插件中有几个值得注意的变化:


@vue/cli-service 

模板块中的空格处理

为了打包 bundle 更小,

我们在 Vue CLI v3中默认禁用了 vue-template-compiler 的preserveWhitespace 选项。


但是,此设置带有一些警告。


幸运的是,自从 Vue 2.6 发布以来,我们现在可以通过新的whitespace选项更好地控制空白处理。

因此我们决定在 Vue CLI v4 中默认使用此新选项


以下面的模板为例:

<p>
  Welcome to <b>Vue.js</b> <i>world</i>.
  Have fun!
</p>


若设置 preserveWhitespace: false, 标签之间的所有空白被删除,编译输出如下:

<p> Welcome to <b>Vue.js</b><i>world</i>. Have fun! </p>


若设置 whitespace: 'condense', 编译输出如下:

<p> Welcome to <b>Vue.js</b> <i>world</i>. Have fun! </p>

注意现在是保留标记之间的内联空白。


vue-cli-service build --mode development

在过去,我们在development模式下运行 build 命令, dist 目录的输出在production 模式下有所差异。现在有了以下两个变化, 所有模式的目录结构都是相同的 (文件名仍然不同 - development 模式下文件名没有hashes(哈希)):


对于 SASS/SCSS 用户

在Vue CLI v3, 我们默认集成了 sass-loader@7


最近 sass-loader@8 已经释并且已经改变了很多配置格式

这里查看正式版发布概要: https://github.com/webpack-contrib/sass-loader/releases/tag/v8.0.0


在v4中@vue/cli-service 依然支持 sass-loader@7 ,

但我们强烈建议你查看v8版本并升级到最新版本。


对于 Less用户

less-loader v4 与 less >= v3.10不兼容, 请查看 https://github.com/less/less.js/issues/3414

如果你项目依有依赖赖它,我们强烈建议你升级到 less-loader@5 。


对于 CSS模块用户


vue.config.js 选项

现已移除废弃baseUrl 选项


chainWebpack / configureWebpack

chainWebpack中的minimizerde 的方法

如果你已经自定义了 chainWebpack的内部规则, 请注意 webpack-chain 已经从v4升级到v6的变更, 最明显的变化是 minimizer 配置

例如,如果您想在 terser 插件中启用 drop_console 选项。在 v3 中,您可以在 chainWebpack 中这样配置:

const TerserPlugin = require('terser-webpack-plugin')
module.exports = {
  chainWebpack: (config) => {
    config.optimization.minimizer([
      new TerserPlugin({ terserOptions: { compress: { drop_console: true } } })
    ])
  }
}

在v4,改成了这样:

module.exports = {
  chainWebpack: (config) => {
    config.optimization.minimizer('terser').tap((args) => {
      args[0].terserOptions.compress.drop_console = true
      return args
    })
  }
}
 其他变化


底层加载器/插件

对用户影响基本无感知的,除非你自定义了 chainWebpack / configureWebpack的相关选项。

css-loader 从v1升级到v3:

其他几个底层的 webpack 加载器和插件也升级,变化不是很大:

url-loader from v1 to v2


@vue/cli-plugin-babel, @vue/babel-preset-app

core-js

babel需要的一个关联依赖, 用于转译代码中使用的polyfill。

在Vue CLI v3, 所需的 core-js 版本是2.x,如今升级到 3.x.

如果你是通过命令 vue upgrade babel 则该迁移升级是自动的。

但是如果你有自定义 polyfills 引入, 你可能需要手动调整 polyfill名称(更多详情, 请看 core-js changelog)。


Babel预设

如果你是通过命令 vue upgrade babel 则该迁移升级也是自动的

这是因为 @vue/babel-preset-app 确实是对项目间接依赖。 之所以有效是因为 npm's package hoisting. 若是项目中有多个冲突都间接依赖了它,潜在隐患还是会发生 ,或者如果包管理器对依赖解析设置了更严格的约束 (例如 yarn plug'n'play 或者 pnpm)。所以我们现在把它移到项目的直接依赖 (@vue/cli-plugin-babel) 使其更符合标准,不易出错。


@vue/cli-plugin-eslint

现在该插件需要 ESLint 作为关联依赖

这不会影响 Vue CLI 3.1 或更高版本初始化的项目。

如果您的项目是用 Vue CLI 3.0.x 或更早版本搭建的, 你可能需要添加 eslint@4 到你的项目依赖中(如果升级插件使用的运行 vue upgrade eslint则该过程是自动的).

建议将 ESLint 升级到 v5,并将 ESLint 配置版本升级到最新版本。(ESLint v6 支持仍在进行中)


Prettier预设

我们prettier预设的旧实现是有缺陷的。自Vue CLI v3.10起,我们更新了默认模板。

它现在需要 eslint, eslint-plugin-prettier 和 prettier 作为关联依赖(间接依赖),

遵循ESLint生态系统中的标准实践


对于较旧的项目, 如果你遇到像 Cannot find module: eslint-plugin-prettier这类问题,

请运行以下命令来修复它:

npm install --save-dev eslint@5 @vue/eslint-config-prettier@5 eslint-plugin-prettier prettier


lintOnSave 选项

(以下仅影响开发)

lintOnSave 选项的默认值 (当没有指定时) true 变更为 'default'

您可以从该 文档中了解更多详情信息。

简而言之:


@vue/cli-plugin-pwa

底层的 workbox-webpack-plugin 已经从 v3 升级到 v4。 请看 版本发行记录


还提供 pwa.manifestOptions 有效配置字段 (可以在 vue.config.js配置)。

有了这个新选项,manifest.json 将从配置对象生成,而非直接从 public 目录。

提供了更加一致接口来管理你的 PWA 配置。(注意,这是一个可选的功能。相关PRs: #2981, #4664)


@vue/cli-plugin-e2e-cypress

在Vue CLI v3.0.0-beta.10之前, E2E 测试的默认命令是 vue-cli-service e2e

之后我们变更为vue-cli-service test:e2e

之前的命令虽已弃用但仍支持。我们现在已经完全 放弃对这个遗留命令的支持


@vue/cli-plugin-e2e-nightwatch

Nightwatch.js 已经从 0.9 升级到 1.x。请务必先阅读 Nightwatch迁移指南

bundle配置和生成的测试有很大的改动, 详情请点击链接。

Vue CLI v3 中的大多数用例仍然受支持。它们只是新功能。

由于 ChromeDriver 自 73 版本以来改变了其版本策略, 我们把它作为项目的关联依赖(间接依赖)。

在插件中实现了一个简单的浏览器版本检查, 因此如果你已经升级到不兼容的 Chrome 版本将会发出警告,

提示您升级所依赖的 ChromeDriver 版本。



在 cypress 插件中,对旧版vue-cli-service e2e命令的支持也已删除。.

@vue/cli-plugin-typescript

但使用Typescript时,webpack解析选项相比 js(x)后缀文件更优先解析ts(x)文件.


@vue/cli-plugin-unit-jest

我们已经将内置的Jest 从 v23 升级到 v24,请务必先阅读他们的版本发行记录 , 点击该链接获取完整的变更日志

unit-jest 插件现在内置了四个预设:


若你项目创建以来没有更改默认的Jest配置 (位于 jest.config.js 或者  package.jsonjest字段) ,

你现在可以用一个预设字段来取代大量的配置:

module.exports = {
  // Replace the following preset name with the one you want to use from the above list
  preset: '@vue/cli-plugin-unit-jest'
}

(在将配置迁移到预设的配置后也可以删除ts-jest, babel-jest 依赖)


温馨提示

新预设中的默认测试环境是 jsdom@15,区别于Jest 24 (jsdom@11)。

这将与即将到来的 Jest 25 更新保持一致。大多数用户不会受到此更改的影响。

关于jsdom更多的变更详情,请查阅 https://github.com/jsdom/jsdom/blob/master/Changelog.md


@vue/cli-plugin-unit-mocha


@vue/cli-service-global

查阅 @vue/cli-service & @vue/cli-plugin-eslint 包的破坏性变更。