⚠️ Vue CLI 处于维护模式!

对于新项目,现在建议使用 create-vue 来搭建基于 Vite 的项目。还可以参考 Vue 3 工具指南 获取最新建议。

配置参考

全局 CLI 配置

@vue/cli 的一些全局配置,例如你喜欢的包管理器和本地保存的预设,都存储在你主目录中的名为 .vuerc 的 JSON 文件中。你可以使用你选择的编辑器直接编辑此文件来更改保存的选项。

你也可以使用 vue config 命令来检查或修改全局 CLI 配置。

目标浏览器

请参阅指南中的 浏览器兼容性 部分。

vue.config.js

vue.config.js 是一个可选的配置文件,如果它存在于你的项目根目录(与 package.json 相邻),则会由 @vue/cli-service 自动加载。你也可以使用 package.json 中的 vue 字段,但请注意,在这种情况下,你将仅限于 JSON 兼容的值。

该文件应导出包含选项的对象

// vue.config.js

/**
 * @type {import('@vue/cli-service').ProjectOptions}
 */
module.exports = {
  // options...
}

或者,你可以使用 @vue/cli-service 中的 defineConfig 帮助程序,它可以提供更好的智能感知支持

// vue.config.js
const { defineConfig } = require('@vue/cli-service')

module.exports = defineConfig({
  // options...
})

baseUrl

从 Vue CLI 3.3 开始已弃用,请改用 publicPath

publicPath

  • 类型:string

  • 默认值:'/'

    你的应用程序包将部署到的基本 URL(在 Vue CLI 3.3 之前称为 baseUrl)。这等效于 webpack 的 output.publicPath,但 Vue CLI 也需要此值用于其他目的,因此你应该始终使用 publicPath 而不是修改 webpack output.publicPath

    默认情况下,Vue CLI 假设你的应用程序将部署在域的根目录下,例如 https://www.my-app.com/。如果你的应用程序部署在子路径下,则需要使用此选项指定该子路径。例如,如果你的应用程序部署在 https://www.foobar.com/my-app/,则将 publicPath 设置为 '/my-app/'

    该值也可以设置为空字符串 ('') 或相对路径 (./),以便所有资产都使用相对路径链接。这允许构建的包部署在任何公共路径下,或用于基于文件系统的环境,例如 Cordova 混合应用程序。

    相对 publicPath 的限制

    相对 publicPath 有一些限制,应避免在以下情况下使用

    • 你正在使用 HTML5 history.pushState 路由;

    • 你正在使用 pages 选项来构建多页面应用程序。

    此值在开发期间也会被尊重。如果你希望你的开发服务器在根目录下提供服务,可以使用条件值

    module.exports = {
      publicPath: process.env.NODE_ENV === 'production'
        ? '/production-sub-path/'
        : '/'
    }
    

outputDir

  • 类型:string

  • 默认值:'dist'

    运行 vue-cli-service build 时生成生产构建文件的目录。请注意,目标目录内容将在构建之前被删除(可以通过在构建时传递 --no-clean 来禁用此行为)。

    提示

    始终使用 outputDir 而不是修改 webpack output.path

assetsDir

  • 类型:string

  • 默认值:''

    一个目录(相对于 outputDir),用于将生成的静态资产(js、css、img、fonts)嵌套在其中。

    提示

    assetsDir 在覆盖生成的资产的 filename 或 chunkFilename 时会被忽略。

indexPath

  • 类型:string

  • 默认值:'index.html'

    指定生成的 index.html 的输出路径(相对于 outputDir)。也可以是绝对路径。

filenameHashing

  • 类型:boolean

  • 默认值:true

    默认情况下,生成的静态资产在其文件名中包含哈希值,以更好地控制缓存。但是,这需要由 Vue CLI 自动生成 index HTML。如果你无法使用由 Vue CLI 生成的 index HTML,可以通过将此选项设置为 false 来禁用文件名哈希。

pages

  • 类型:Object

  • 默认值:undefined

    以多页面模式构建应用程序。每个“页面”都应该有一个对应的 JavaScript 入口文件。该值应该是一个对象,其中键是入口的名称,值是

    • 一个对象,指定其 entrytemplatefilenametitlechunks(除了 entry 之外,所有都是可选的)。除了这些属性之外,添加的任何其他属性也将直接传递给 html-webpack-plugin,允许用户自定义该插件;
    • 或者是一个字符串,指定其 entry
    module.exports = {
      pages: {
        index: {
          // entry for the page
          entry: 'src/index/main.js',
          // the source template
          template: 'public/index.html',
          // output as dist/index.html
          filename: 'index.html',
          // when using title option,
          // template title tag needs to be <title><%= htmlWebpackPlugin.options.title %></title>
          title: 'Index Page',
          // chunks to include on this page, by default includes
          // extracted common chunks and vendor chunks.
          chunks: ['chunk-vendors', 'chunk-common', 'index']
        },
        // when using the entry-only string format,
        // template is inferred to be `public/subpage.html`
        // and falls back to `public/index.html` if not found.
        // Output filename is inferred to be `subpage.html`.
        subpage: 'src/subpage/main.js'
      }
    }
    

    提示

    在多页面模式下构建时,webpack 配置将包含不同的插件(将有多个 html-webpack-pluginpreload-webpack-plugin 实例)。如果你尝试修改这些插件的选项,请确保运行 vue inspect

lintOnSave

  • 类型:boolean | 'warning' | 'default' | 'error'

  • 默认值:'default'

    是否在开发过程中使用 eslint-loader 执行 lint-on-save。此值仅在安装了 @vue/cli-plugin-eslint 时生效。

    当设置为 true'warning' 时,eslint-loader 将 lint 错误作为警告发出。默认情况下,警告仅记录到终端,不会导致编译失败,因此这是开发的良好默认值。

    要使 lint 错误显示在浏览器覆盖层中,可以使用 lintOnSave: 'default'。这将强制 eslint-loader 实际发出错误。这也意味着 lint 错误现在会导致编译失败。

    将其设置为 'error' 将强制 eslint-loader 将警告也作为错误发出,这意味着警告也会显示在覆盖层中。

    或者,你可以配置覆盖层以显示警告和错误

    // vue.config.js
    module.exports = {
      devServer: {
        overlay: {
          warnings: true,
          errors: true
        }
      }
    }
    

    lintOnSave 是一个真值时,eslint-loader 将在开发和生产中应用。如果你想在生产构建期间禁用 eslint-loader,可以使用以下配置

    // vue.config.js
    module.exports = {
      lintOnSave: process.env.NODE_ENV !== 'production'
    }
    

runtimeCompiler

  • 类型:boolean

  • 默认值:false

    是否使用包含运行时编译器的 Vue 核心构建。将其设置为 true 将允许您在 Vue 组件中使用 template 选项,但会给您的应用程序带来大约 10kb 的额外负载。

    另请参阅:运行时 + 编译器与仅运行时

transpileDependencies

  • 类型:boolean | Array<string | RegExp>

  • 默认值:false

    默认情况下,babel-loader 会忽略 node_modules 中的所有文件。您可以启用此选项以避免第三方依赖项中出现意外的未转译代码。

    但是,转译所有依赖项可能会减慢构建过程。如果构建性能是一个问题,您可以通过将包名称或名称模式的数组传递给此选项来显式地仅转译某些依赖项。

Jest 配置

此选项不受 cli-unit-jest 插件 的影响,因为在 jest 中,我们不必转译来自 /node_modules 的代码,除非它使用非标准功能 - Node >8.11 已经支持最新的 ECMAScript 功能。

但是,如果该代码使用 ES6 import/export 语法,jest 有时需要转换来自 node_modules 的内容。在这种情况下,请在 jest.config.js 中使用 transformIgnorePatterns 选项。

有关更多信息,请参阅 插件的 README

productionSourceMap

  • 类型:boolean

  • 默认值:true

    如果生产环境不需要源映射,将此设置为 false 可以加快生产构建速度。

crossorigin

  • 类型:string

  • 默认值:undefined

    在生成的 HTML 中配置 <link rel="stylesheet"><script> 标签上的 crossorigin 属性。

    请注意,这只会影响由 html-webpack-plugin 注入的标签 - 直接添加到源模板 (public/index.html) 中的标签不受影响。

    另请参阅:CORS 设置属性

integrity

  • 类型:boolean

  • 默认值:false

    设置为 true 以在生成的 HTML 中的 <link rel="stylesheet"><script> 标签上启用 子资源完整性 (SRI)。如果您将构建的文件托管在 CDN 上,为了额外的安全性,最好启用此功能。

    请注意,这只会影响由 html-webpack-plugin 注入的标签 - 直接添加到源模板 (public/index.html) 中的标签不受影响。

    此外,当启用 SRI 时,预加载资源提示会因 Chrome 中的错误 而被禁用,该错误会导致资源被下载两次。

configureWebpack

  • 类型:Object | Function

    如果该值为对象,它将使用 webpack-merge 合并到最终配置中。

    如果该值为函数,它将接收解析后的配置作为参数。该函数可以修改配置并返回空值,或者返回配置的克隆或合并版本。

    另请参阅:使用 Webpack > 简单配置

chainWebpack

css.modules

css.requireModuleExtension

两者在 v5 中都已删除,请参阅 使用 CSS > CSS 模块 以了解如何将所有样式导入视为 CSS 模块。

css.extract

  • 类型:boolean | Object

  • 默认:生产环境为 true,开发环境为 false

    是否将组件中的 CSS 提取到独立的 CSS 文件中(而不是内联到 JavaScript 中并动态注入)。

    当以 Web 组件形式构建时,这始终被禁用(样式被内联并注入到 shadowRoot 中)。

    当以库形式构建时,您也可以将其设置为 false 以避免您的用户必须自己导入 CSS。

    在开发模式下,默认情况下会禁用提取 CSS,因为它与 CSS 热重载不兼容。但是,您仍然可以通过将该值显式设置为 true 来强制在所有情况下进行提取。

    除了 true 之外,您还可以传递一个 mini-css-extract-plugin 选项对象,如果您想进一步配置此插件的具体行为。

css.sourceMap

  • 类型:boolean

  • 默认值:false

    是否为 CSS 启用源映射。将此设置为 true 可能会影响构建性能。

css.loaderOptions

  • 类型:Object

  • 默认:{}

    将选项传递给与 CSS 相关的加载器。例如

    module.exports = {
      css: {
        loaderOptions: {
          css: {
            // options here will be passed to css-loader
          },
          postcss: {
            // options here will be passed to postcss-loader
          }
        }
      }
    }
    

    支持的加载器是

    还可以使用 scss 选项单独针对 scss 语法。

    另请参阅:将选项传递给预处理器加载器

    提示

    这比使用 chainWebpack 手动访问特定加载器更可取,因为这些选项需要在使用相应加载器的多个位置应用。

devServer

  • 类型:Object

    webpack-dev-server 的所有选项 都受支持。请注意

    • 某些值(如 hostporthttps)可能会被命令行标志覆盖。

    • 某些值(如 publicPathhistoryApiFallback)不应修改,因为它们需要与 publicPath 同步才能使开发服务器正常运行。

devServer.proxy

  • 类型:string | Object

    如果您的前端应用程序和后端 API 服务器不在同一主机上运行,您需要在开发过程中将 API 请求代理到 API 服务器。这可以通过 vue.config.js 中的 devServer.proxy 选项进行配置。

    devServer.proxy 可以是一个指向开发 API 服务器的字符串

    module.exports = {
      devServer: {
        proxy: 'https://127.0.0.1:4000'
      }
    }
    

    这将告诉开发服务器将任何未知请求(与静态文件不匹配的请求)代理到 https://127.0.0.1:4000

    警告

    devServer.proxy 设置为字符串时,只有 XHR 请求会被代理。如果您想测试 API URL,请不要在浏览器中打开它,而是使用 API 工具(如 Postman)。

    如果您想对代理行为有更多控制,您也可以使用带有 path: options 对的 对象。有关完整选项,请咨询 http-proxy-middleware

    module.exports = {
      devServer: {
        proxy: {
          '^/api': {
            target: '<url>',
            ws: true,
            changeOrigin: true
          },
          '^/foo': {
            target: '<other_url>'
          }
        }
      }
    }
    

devServer.inline

  • 类型:boolean

  • 默认值:true

    在开发服务器的两种不同模式之间切换。有关更多详细信息,请参阅 devServer.inline。请注意

    • 要使用 iframe 模式,无需任何额外配置。只需将浏览器导航到 http://<host>:<port>/webpack-dev-server/<path> 即可调试您的应用程序。应用程序顶部会出现一个带有消息的通知栏。
    • 要使用 内联模式,只需导航到 http://<host>:<port>/<path> 即可调试您的应用程序。构建消息将出现在浏览器控制台中。

parallel

  • 类型:boolean | number

  • 默认:require('os').cpus().length > 1

    是否为 Babel 或 TypeScript 转译使用 thread-loader。当系统拥有超过 1 个 CPU 内核时,这将在生产构建中启用。传递一个数字将定义使用的 worker 数量。

警告

不要将 parallel 与不可序列化的加载器选项(如正则表达式、日期和函数)结合使用。这些选项不会正确传递给相应的加载器,这可能会导致意外错误。

pwa

pluginOptions

  • 类型:Object

    这是一个不经过任何模式验证的对象,因此它可以用来将任意选项传递给第三方插件。例如

    module.exports = {
      pluginOptions: {
        foo: {
          // plugins can access these options as
          // `options.pluginOptions.foo`.
        }
      }
    }
    

Babel

Babel 可以通过 babel.config.js 进行配置。

提示

Vue CLI 使用 babel.config.js,这是 Babel 7 中的一种新的配置格式。与 .babelrcpackage.json 中的 babel 字段不同,此配置文件不使用基于文件位置的解析,并且一致地应用于项目根目录下的任何文件,包括 node_modules 中的依赖项。建议在 Vue CLI 项目中始终使用 babel.config.js 而不是其他格式。

所有 Vue CLI 应用程序都使用 @vue/babel-preset-app,其中包括 babel-preset-env、JSX 支持以及针对最小捆绑包大小开销的优化配置。有关详细信息和预设选项,请参阅 其文档

另请参阅指南中的 Polyfills 部分。

ESLint

ESLint 可以通过 .eslintrcpackage.json 中的 eslintConfig 字段进行配置。

有关更多详细信息,请参阅 @vue/cli-plugin-eslint

TypeScript

TypeScript 可以通过 tsconfig.json 进行配置。

有关更多详细信息,请参阅 @vue/cli-plugin-typescript

单元测试

Jest

有关更多详细信息,请参阅 @vue/cli-plugin-unit-jest

Mocha(通过 mocha-webpack

有关更多详细信息,请参阅 @vue/cli-plugin-unit-mocha

E2E 测试

Cypress

有关更多详细信息,请参阅 @vue/cli-plugin-e2e-cypress

Nightwatch

有关更多详细信息,请参阅 @vue/cli-plugin-e2e-nightwatch

WebdriverIO

有关更多详细信息,请参阅 @vue/cli-plugin-e2e-webdriverio