从 v3 迁移 #

首先，全局安装最新版本的 Vue CLI

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

一次性升级所有插件 #

在您现有的项目中，运行

vue upgrade

然后查看以下部分，了解每个包中引入的详细重大变更。

逐个手动迁移 #

如果您想手动逐步迁移，以下是一些提示

全局 @vue/cli #

重新设计 vue upgrade #

• 之前：vue upgrade [patch | minor | major]，它只安装最新版本的 Vue CLI 插件。
• 之后：vue upgrade [plugin-name]。除了升级插件外，它还可以运行插件的迁移器，帮助您自动执行迁移过程。有关此命令的更多选项，请运行 vue upgrade --help。

vue --version 输出格式变更 #

运行 vue --version 时

• 3.x：输出 3.12.0
• 4.x：输出 @vue/cli 4.0.0

避免覆盖的额外确认步骤 #

运行 vue invoke / vue add / vue upgrade 时，现在如果您在当前存储库中存在未提交的更改，则会进行 额外确认步骤。

Vue Router 和 Vuex 现在拥有相应的 CLI 插件 #

运行 vue add vuex 或 vue add router 时

• 在 v3 中，只会将 vuex 或 vue-router 添加到项目中；
• 在 v4 中，还会安装 @vue/cli-plugin-vuex 或 @vue/cli-plugin-router。

目前这对最终用户来说没有实际区别，但这种设计允许我们稍后为 Vuex 和 Vue Router 用户添加更多功能。

对于预设和插件作者，这两个插件中有一些值得注意的更改

• 默认目录结构已更改
  • src/store.js 移动到 src/store/index.js；
  • src/router.js 重命名为 src/router/index.js；
• preset.json 中的 router 和 routerHistoryMode 选项出于兼容性原因仍然受支持。但现在建议使用 plugins: { '@vue/cli-plugin-router': { historyMode: true } } 以获得更好的一致性。
• api.hasPlugin('vue-router') 不再受支持。现在是 api.hasPlugin('router')。

@vue/cli-service #

模板块中的空白处理 #

为了获得更小的包，我们在 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 模式下没有哈希值）

• #4323 确保所有模式下的一致目录结构
• #4302 将开发配置移到 serve 命令中

对于 SASS/SCSS 用户 #

之前在 Vue CLI v3 中，我们默认使用 sass-loader@7。

最近 sass-loader@8 已经发布，并且其配置格式发生了很大变化。以下是发布说明：https://github.com/webpack-contrib/sass-loader/releases/tag/v8.0.0

@vue/cli-service 将在 v4 中继续支持 sass-loader@7，但我们强烈建议您查看 v8 版本并升级到最新版本。

对于 Less 用户 #

less-loader v4 与 less >= v3.10 不兼容，请参见 https://github.com/less/less.js/issues/3414。如果您的项目依赖于它，强烈建议升级到 less-loader@5。

对于 CSS 模块用户 #

• 弃用 css.modules，改用 css.requireModuleExtension。这是因为我们已经升级到 css-loader v3，配置格式已更改。有关更详细的说明，请点击链接。

vue.config.js 选项 #

已弃用的 baseUrl 选项 现已 移除

chainWebpack / configureWebpack #

chainWebpack 中的 minimizer 方法 #

如果您已使用 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
    })
  }
}

其他更改 #

• pug-plain 规则已重命名为 pug-plain-loader

底层加载器/插件 #

除非您通过 chainWebpack / configureWebpack 自定义了其选项，否则不太可能影响用户

css-loader 已从 v1 升级到 v3

• v2 变更日志
• v3 变更日志

其他几个底层 webpack 加载器和插件已升级，主要变化很小

• url-loader 从 v1 升级到 v2
• file-loader 从 v3 升级到 v4
• copy-webpack-plugin 从 v4 升级到 v5
• terser-webpack-plugin 从 v1 升级到 v2

@vue/cli-plugin-babel、@vue/babel-preset-app #

core-js #

babel 插件需要一个对等依赖项，用于在转译的代码中使用的 polyfills。

在 Vue CLI v3 中，所需的 core-js 版本为 2.x，现在已升级到 3.x。

如果您通过 vue upgrade babel 升级，此迁移将自动完成。但是，如果您引入了自定义 polyfills，则可能需要手动更新 polyfill 名称（有关更多详细信息，请参阅 core-js 变更日志）。

Babel 预设 #

如果您通过 vue upgrade babel 升级，此迁移也将自动完成。

• 在 v3 中，babel.config.js 中使用的默认 babel 预设为 @vue/app。
• 在 v4 中，我们将其移到了插件中，因此现在它被命名为 @vue/cli-plugin-babel/preset

这是因为 @vue/babel-preset-app 实际上是对项目的间接依赖项。它之所以有效，是因为 npm 的包提升功能。但是，如果项目具有多个相同包的冲突间接依赖项，或者如果包管理器对依赖项解析施加了更严格的约束（例如 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'。您可以在 文档 中阅读有关详细说明的更多信息。

简而言之

• 在 v3 中，默认情况下，lint 警告以及错误将显示在错误覆盖层中
• 在 v4 中，默认情况下，只有 lint 错误会中断您的开发过程。警告仅在终端控制台中记录。

@vue/cli-plugin-pwa #

底层的 workbox-webpack-plugin 已从 v3 升级到 v4。请参阅 此处的发行说明。

还有一个 pwa.manifestOptions 字段可用（您可以在 vue.config.js 中设置它）。使用此新选项，manifest.json 将从配置对象生成，而不是直接从 public 文件夹复制。这为管理您的 PWA 配置提供了更一致的界面。（注意，这是一个可选功能。相关 PR：#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 迁移指南。

捆绑的配置和生成的测试 已完全改版。请点击链接了解更多详细信息。Vue CLI v3 中的大多数用例仍然受支持。它们只是新功能。

由于 ChromeDriver 自版本 73 以来已更改其版本策略，因此我们已将其作为项目的对等依赖项。插件中实现了简单的浏览器版本检查，因此，如果您已升级到不兼容版本的 Chrome，将会有一个警告提示您升级依赖的 ChromeDriver 版本。

与 cypress 插件一样，对旧的 vue-cli-service e2e 命令的支持也已删除。

@vue/cli-plugin-typescript #

在导入没有扩展名的文件时，webpack 解析选项现在 优先使用 .ts(x) 文件而不是 .js(x) 和 .vue 文件。我们强烈建议您在导入 .vue 文件时始终包含文件扩展名。

@vue/cli-plugin-unit-jest #

我们已将捆绑的 Jest 从 v23 升级到 v24，因此请先阅读其 发行说明。请点击 此链接 查看完整的变更日志。

unit-jest 插件现在附带 4 个配置预设

• @vue/cli-plugin-unit-jest 适用于最常见类型项目的默认预设
• @vue/cli-plugin-unit-jest/presets/no-babel 如果您没有安装 @vue/cli-plugin-babel，并且不想在项目中看到 babel 文件
• @vue/cli-plugin-unit-jest/presets/typescript 支持 TypeScript 的预设（但不支持 TSX）
• @vue/cli-plugin-unit-jest/presets/typescript-and-babel 支持 TypeScript（和 TSX）以及 babel 的预设。

如果您自项目创建以来从未更改过默认的 Jest 配置（位于 jest.config.js 或 package.json 中的 jest 字段中），那么现在您可以用一个字段替换庞大的配置对象

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 依赖项）

@vue/cli-plugin-unit-mocha #

• 使用 mochapack 代替 mocha-webpack，请查看 https://github.com/sysgears/mochapack/releases 中的变更日志。此更改不太可能影响实际使用。
• 升级到 mocha 6，请查看 Mocha 的变更日志 获取更多详细信息。

@vue/cli-service-global #

请查看 @vue/cli-service 和 @vue/cli-plugin-eslint 包中的重大变更。