Vue CLI 配置完全指南从 vue.config.js 到全局 CLI 设置【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli本篇技术指南围绕 Vue CLIwebpack-based tooling for Vue.js Development的配置体系展开覆盖全局 CLI 配置.vuerc与vue config命令、vue.config.js中全部核心选项部署路径、多页面、Lint、CSS、devServer 代理、Webpack 定制等以及 Babel / ESLint / TypeScript 与测试工具链的配置方式。阅读本文后你将掌握 Vue CLI 配置的完整脉络并能结合实际源码理解每个选项背后的生效机制从容应对各类构建与部署场景。全局 CLI 配置vue/cli的一些全局设置——例如偏好的包管理器packageManager、本地保存的 presetpresets——存储在用户主目录下的 JSON 文件.vuerc中。你可以用任意编辑器直接修改该文件来调整已保存的选项。除了手工编辑更推荐使用vue config命令来查看或修改全局 CLI 配置。该命令的实现位于 packages/vue/cli/lib/config.js支持以下子命令子命令作用vue config打印.vuerc文件解析路径与完整内容JSON 格式化vue config --get key读取指定键的值如vue config --get packageManagervue config --set key value写入指定键源码中会自动把纯数字字符串转为整数、把true/false转为布尔值vue config --delete key删除指定键vue config --edit用系统默认编辑器打开.vuercvue config --json以 JSON 形式输出供脚本消费输出包含resolvedPath与content等字段目标浏览器browserslistVue CLI 使用browserslist配置来确定项目需要转译的 JavaScript 特性与需要添加的 CSS 厂商前缀。你可以在package.json的browserslist字段或独立的.browserslistrc文件中声明目标浏览器范围。该值会被babel/preset-env与autoprefixer消费具体机制详见 docs/guide/browser-compatibility.md。默认的 Vue CLI 项目通过vue/babel-preset-app使用babel/preset-env并默认传入useBuiltIns: usage即按源码实际用到的语言特性自动注入最小化 polyfill 集合。需要说明的是这意味着一部分第三方依赖自身的 polyfill 需求无法被自动检测——当依赖需要 polyfill 时可以显式配置vue/babel-preset-app的polyfills选项或在入口文件中使用useBuiltIns: entry并引入core-js/stable等方式解决。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 { // 配置项... }也可以使用vue/cli-service提供的defineConfig帮助函数以获得更好的类型提示IntelliSense支持// vue.config.js const { defineConfig } require(vue/cli-service) module.exports defineConfig({ // 配置项... })defineConfig的实现位于 packages/vue/cli-service/lib/Service.js本质上只是原样返回传入的配置对象用于获得类型标注支持。配置文件加载与合并的源码机制从源码可以更清楚地看到配置的完整生命周期。在 packages/vue/cli-service/lib/util/loadFileConfig.js 中配置文件的查找顺序是process.env.VUE_CLI_SERVICE_CONFIG_PATH环境变量指定路径./vue.config.js./vue.config.cjs./vue.config.mjs并且会根据is-file-esm的检测结果决定用import()还是require()加载因此 ESM 与 CJS 风格的配置文件都被支持。在 packages/vue/cli-service/lib/util/resolveUserConfig.js 中确定了三者的优先级vue.config.js文件配置 package.json的vue字段 内联选项inlineOptions。若同时存在文件配置与vue字段后者会被忽略并给出迁移警告。该模块还会做两项规范化处理publicPath末尾自动补/除非是auto并去掉开头的./前缀outputDir末尾的多余斜杠会被移除。随后配置会交给 packages/vue/cli-service/lib/options.js 中定义的 Joi schema 做校验任何非法值都会在启动时报错。在 packages/vue/cli-service/lib/Service.js 中加载到的用户配置会通过defaultsDeep(loadedUserOptions, defaults())与默认值深度合并再依次应用内置插件与chainWebpack/configureWebpack回调。部署与输出路径相关选项baseUrl已废弃自 Vue CLI 3.3 起请改用publicPath。publicPath类型string默认值/应用构建产物将要部署的基准 URLVue 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/则应设置为/my-app/。值也可以是空字符串或相对路径./此时所有资源将使用相对路径引用适合部署到任意公共目录或用于 Cordova 混合应用这类基于文件系统的环境。::: warning 相对 publicPath 的限制 使用相对publicPath时需注意以下场景应避免使用 HTML5history.pushState路由使用pages选项构建多页面应用MPA。 :::该值在开发阶段同样生效。若希望开发服务器从根路径提供服务可以按环境条件取值module.exports { publicPath: process.env.NODE_ENV production ? /production-sub-path/ : / }在源码层面publicPath通过 packages/vue/cli-service/lib/config/base.js 写入 webpack 的output.publicPath同时 packages/vue/cli-service/lib/Service.js 中还有一道守卫构建目标非app时若检测到output.publicPath与projectOptions.publicPath不一致会直接抛出错误提示改用vue.config.js中的publicPath。outputDir类型string默认值dist运行vue-cli-service build时生产构建产物的输出目录。注意每次构建前该目录会被清空可通过--no-clean参数关闭此行为。::: tip 始终使用outputDir而不要修改 webpack 的output.path。 :::assetsDir类型string默认值用于存放生成的静态资源js、css、img、fonts的目录相对outputDir。::: tip 当覆盖了生成资源的filename或chunkFilename时assetsDir会被忽略。 :::indexPath类型string默认值index.html生成的index.html的输出路径相对outputDir也可以指定绝对路径。在 packages/vue/cli-service/lib/config/app.js 中可以看到当indexPath不是默认值时Vue CLI 会借助内置的MovePlugin把构建生成的index.html移动到目标位置。filenameHashing类型boolean默认值true默认情况下生成的静态资源文件名会包含内容哈希contenthash便于缓存管理。但这一行为依赖 Vue CLI 自动生成的index.html若你无法使用 CLI 生成的 HTML可以将此选项设为false以关闭文件名哈希。源码中哈希格式为js/[name].[contenthash:8].js与css/[name].[contenthash:8].css参见 packages/vue/cli-service/lib/config/app.js 与 packages/vue/cli-service/lib/config/css.js。pages多页面应用MPA类型Object默认值undefined以多页面模式构建应用。每个「页面」都应有对应的 JavaScript 入口文件。值是一个对象键为入口名称值可以是一个对象可指定entry、template、filename、title与chunks除entry外均可选。这些属性之外的其他属性会被原样传给html-webpack-plugin用于更精细地定制该插件或一个字符串直接指定其entry。module.exports { pages: { index: { // 页面入口 entry: src/index/main.js, // 源模板 template: public/index.html, // 输出为 dist/index.html filename: index.html, // 使用 title 选项时模板中的 title 需写成 // title% htmlWebpackPlugin.options.title %/title title: Index Page, // 该页面引入的 chunks默认是 // 抽出的公共 chunk 与 vendor chunk chunks: [chunk-vendors, chunk-common, index] }, // 使用仅入口的字符串格式时 // 模板会被推断为 public/subpage.html // 若不存在则回退到 public/index.html。 // 输出文件名被推断为 subpage.html。 subpage: src/subpage/main.js } }::: tip 在多页面模式下webpack 配置会包含多个html-webpack-plugin与preload-webpack-plugin实例。如果你要修改这些插件的配置请先用vue inspect检查实际配置。 :::从源码看packages/vue/cli-service/lib/config/app.js 会清空默认入口遍历pages中的每个页面字符串格式会被归一化为{ entry: c }entry支持字符串或数组数组会逐一api.resolve后合并进该入口模板按public/name.html推断不存在时回退到public/index.html再回退到内置默认模板每个页面生成独立的html-name插件实例。默认的chunks为[chunk-vendors, chunk-common, name]与文档中的示例一致。开发与代码质量选项lintOnSave类型boolean | warning | default | error默认值default是否在开发过程中保存文件时执行 lint。该选项仅在安装了vue/cli-plugin-eslint时生效。值为true或warning时lint 错误会作为警告输出。默认警告只打印到终端、不会中断编译因此是适合开发的默认行为值为default时lint 错误会真正作为错误上报从而显示在浏览器 overlay 中同时 lint 错误会导致编译失败值为error时lint 警告也会被当作错误处理同样显示在 overlay 中。也可以在devServer.overlay中配置同时展示警告与错误// vue.config.js module.exports { devServer: { overlay: { warnings: true, errors: true } } }当lintOnSave为真值时eslint 会在开发与生产构建中都生效若只想在开发阶段启用可以这样配置// vue.config.js module.exports { lintOnSave: process.env.NODE_ENV ! production }源码实现位于 packages/vue/cli-plugin-eslint/index.jstreatAllAsWarnings lintOnSave true || lintOnSave warning、treatAllAsErrors lintOnSave error并由此推导出failOnWarning与failOnError传入eslint-webpack-plugin最终通过webpackConfig.plugin(eslint)挂载。该插件还基于 ESLint 版本与package.json内容生成缓存标识避免升级 ESLint 插件后使用过期缓存。runtimeCompiler类型boolean默认值false是否使用包含模板编译器的 Vue 构建版本。设为true后可以在 Vue 组件中使用template选项但会为应用额外增加约 10KB 的体积。这与「Runtime Compiler vs. Runtime-only」的取舍有关默认的 runtime-only 构建体积更小但无法在运行时编译模板字符串。transpileDependencies类型boolean | Arraystring | RegExp默认值false默认情况下babel-loader会忽略node_modules内的所有文件。如果第三方依赖包含未被转译的代码可以通过此选项启用转译。转译全部依赖会拖慢构建因此更推荐传入包名或名称模式组成的数组只显式转译个别依赖。在 packages/vue/cli-service/lib/options.js 中该选项的 schema 允许boolean或数组。::: warning Jest 配置说明 该选项不被cli-unit-jest插件支持在 Jest 中除非依赖使用了非标准特性否则无需转译node_modules中的代码Node 8.11 已支持最新的 ECMAScript 特性。若依赖使用了 ES6import/export语法需要转换请在jest.config.js中使用transformIgnorePatterns选项。更多信息见 docs/core-plugins/unit-jest.md。 :::productionSourceMap类型boolean默认值true源码中为!process.env.VUE_CLI_TEST测试环境下自动关闭生产构建是否需要 source map。如果不需要生产环境的 source map设为false可以加快生产构建速度。源码默认值见 packages/vue/cli-service/lib/options.js。HTML 标签安全与完整性crossorigin类型string默认值undefined为生成的 HTML 中link relstylesheet与script标签配置crossorigin属性。注意仅影响html-webpack-plugin注入的标签直接写在源模板public/index.html里的标签不受影响。schema 中允许的取值为、anonymous、use-credentials见 packages/vue/cli-service/lib/options.js。integrity类型boolean默认值false设为true可为生成的 HTML 中link与script标签启用 Subresource IntegritySRI。当构建产物托管在 CDN 上时推荐开启以增强安全性。同样只影响html-webpack-plugin注入的标签。另外启用 SRI 后preload 资源提示会被禁用——这是为了规避 Chrome 中导致资源被下载两次的已知缺陷Chromium issue 677022。crossorigin与integrity在源码中由内置的CorsPlugin实现见 packages/vue/cli-service/lib/config/app.js 与 packages/vue/cli-service/lib/webpack/CorsPlugin.js。定制 Webpack 配置configureWebpack类型Object | Function值为对象时会通过webpack-merge合并进最终配置值为函数时函数会接收解析后的最终配置作为参数可以原地修改配置而不返回任何值或返回一份克隆/合并后的新配置。在 packages/vue/cli-service/lib/Service.js 的resolveWebpackConfig中可以看到函数形式下返回值非空时执行merge(config, res)字面量形式下执行merge(config, fn)。注意合并后会通过cloneRuleNames恢复webpack-chain注入的__ruleNames信息以保证vue inspect正常工作。更多用法可参考 docs/guide/webpack.md。chainWebpack类型Function函数会接收一个由webpack-chain提供的ChainableConfig实例从而对内部 webpack 配置进行更细粒度的链式修改。这是比configureWebpack更进阶的定制方式适合需要精确控制 loader 规则、插件实例等场景。用法见 docs/guide/webpack.md。在 packages/vue/cli-service/lib/Service.js 中用户配置的chainWebpack会被推入webpackChainFns随后在resolveChainableWebpackConfig中依次应用到webpack-chain的Config实例上。CSS 相关选项css.modules已废弃自 v4 起废弃请改用css.requireModuleExtension。在 v3 中它是css.requireModuleExtension的取反。需要说明的是在当前仓库版本v5中这两个选项均已从 packages/vue/cli-service/lib/options.js 的 schema 中移除——CSS Modules 统一通过*.module.[ext]文件名约定识别。css.requireModuleExtension类型boolean默认值true默认情况下只有以*.module.[ext]结尾的文件才被当作 CSS Modules 处理。设为false后可以去掉文件名中的.module让所有*.(css|scss|sass|less|styl(us)?)文件都被当作 CSS Modules。::: tip 若在css.loaderOptions.css中配置了 CSS Modules 相关参数则css.requireModuleExtension必须显式指定为true或false否则无法确定这些参数是否应作用于所有 CSS 文件。 :::从源码看packages/vue/cli-service/lib/config/css.js 为每种样式语言创建了四条oneOf规则vue-modulesstyle module、vue普通style、normal-modules*.module.*文件与normal普通 CSS 导入style module与*.module.*会强制开启 CSS Modulesmodules.auto: () true。更多信息见 docs/guide/css.md。css.extract类型boolean | Object默认值production 下为truedevelopment 下为false是否把组件中的 CSS 抽取到独立的 CSS 文件而不是内联进 JavaScript 动态注入。注意构建 Web Components 时该选项始终被关闭样式会内联进 shadowRoot构建库library时也可设为false避免使用方必须自行引入 CSS开发模式下默认关闭抽取因为它与 CSS 热重载不兼容显式设为true可以强制始终抽取除true外也可以传入一个对象作为mini-css-extract-plugin的配置项。源码中extract的默认值即isProdextract isProd抽取时通过mini-css-extract-plugin输出css/[name].[contenthash:8].css并用css-minimizer-webpack-plugin做压缩不抽取时使用vue-style-loader注入样式且生产环境会额外用cssnano对内联样式做压缩见 packages/vue/cli-service/lib/config/css.js。css.sourceMap类型boolean默认值false是否启用 CSS 的 source map。设为true可能影响构建性能。css.loaderOptions类型Object默认值{}向 CSS 相关的 loader 传递配置。例如module.exports { css: { loaderOptions: { css: { // 这些选项会传给 css-loader }, postcss: { // 这些选项会传给 postcss-loader } } } }支持的 loader 包括css-loader、postcss-loader、sass-loader、less-loader、stylus-loader。还可以通过scss选项单独配置scss语法与sass区分。schema 见 packages/vue/cli-service/lib/options.js。::: tip 这种方式优于通过chainWebpack手工修改具体 loader因为相关 loader 可能在多处使用这些参数需要被统一应用。源码中loaderOptions会合并进css-loader含sourceMap、importLoaders计算等、postcss-loader以及各预处理器 loader 的 options 中详见 packages/vue/cli-service/lib/config/css.js。 :::另外值得一提的是源码会在项目缺少有效 PostCSS 配置时自动注入autoprefixer作为默认插件并做 PostCSS 版本预检见 packages/vue/cli-service/lib/config/css.js。devServer 与开发代理devServer类型Objectwebpack-dev-server的所有选项均受支持但需注意两点部分值如host、port、https可能被命令行参数覆盖部分值如publicPath、historyApiFallback不应被修改它们必须与publicPath保持同步开发服务器才能正常工作。devServer.proxy类型string | Object当前端应用与后端 API 服务不在同一主机上时需要在开发阶段代理 API 请求可通过devServer.proxy配置。可以传一个字符串指向开发 API 服务器module.exports { devServer: { proxy: http://localhost:4000 } }这会让开发服务器把所有未知请求未匹配到静态文件的请求代理到http://localhost:4000。::: warningdevServer.proxy使用字符串形式时只会代理 XHR 请求。要测试 API URL请不要直接在浏览器中打开而是使用 API 调试工具如 Postman。 :::如需更精细地控制代理行为可以使用path: options键值对的对象形式完整的选项列表可参考http-proxy-middlewaremodule.exports { devServer: { proxy: { ^/api: { target: url, ws: true, changeOrigin: true }, ^/foo: { target: other_url } } } }devServer.inline类型boolean默认值true在开发服务器的两种工作模式间切换iframe mode无需额外配置浏览器访问http://host:port/webpack-dev-server/path即可调试应用页面顶部会出现通知栏inline mode直接访问http://host:port/path调试应用构建消息显示在浏览器控制台中。构建性能与扩展选项parallel类型boolean | number默认值require(os).cpus().length 1机器多于 1 个 CPU 核心时启用是否使用thread-loader并行转译 Babel 或 TypeScript。生产构建在系统多于 1 个 CPU 核心时默认启用传入数字可指定使用的 worker 数量。源码中hasMultipleCores()还做了防御性处理cpus()可能返回 undefined见 packages/vue/cli-service/lib/options.js。::: warning 不要将parallel与不可序列化的 loader 选项如正则、日期、函数组合使用。这些选项无法正确传给相应 loader可能导致意外错误。 :::pwa类型Object传递给 PWA 插件的配置对应vue/cli-plugin-pwa。用于定制 Service Worker 与 Web App Manifest 等行为。pluginOptions类型Object该对象不经过任何结构校验因此可以用于向第三方插件传递任意参数。例如module.exports { pluginOptions: { foo: { // 插件可以通过 options.pluginOptions.foo 访问这些设置 } } }在 packages/vue/cli-service/lib/options.js 中它以joi.object()定义不做内部约束第三方插件在apply阶段从projectOptions.pluginOptions中读取。工具链配置Babel、ESLint 与 TypeScriptBabelBabel 通过babel.config.js配置。::: tip Vue CLI 使用 Babel 7 的新配置格式babel.config.js。与.babelrc或package.json中的babel字段不同该配置文件不基于文件位置解析而是对项目根目录下的所有文件包括node_modules中的依赖一致生效。在 Vue CLI 项目中建议始终使用babel.config.js而非其他格式。 :::所有 Vue CLI 应用都使用vue/babel-preset-app它内置了babel-preset-env、JSX 支持以及为最小化打包体积优化的配置具体实现见 packages/vue/babel-preset-app/index.js。Polyfill 相关策略参见 docs/guide/browser-compatibility.md。ESLintESLint 通过.eslintrc或package.json的eslintConfig字段配置插件实现见 packages/vue/cli-plugin-eslint含 index.js、eslintOptions.js 与 prompts.js。TypeScriptTypeScript 通过tsconfig.json配置插件实现见 packages/vue/cli-plugin-typescript含 tsconfig.json 生成逻辑。测试工具链配置单元测试Jest详见 packages/vue/cli-plugin-unit-jest预置配置位于 packages/vue/cli-plugin-unit-jest/jest-preset.jsMocha通过mocha-webpack详见 packages/vue/cli-plugin-unit-mocha。E2E 测试Cypress详见 packages/vue/cli-plugin-e2e-cypressNightwatch详见 packages/vue/cli-plugin-e2e-nightwatchWebdriverIO详见 packages/vue/cli-plugin-e2e-webdriverio。各测试插件的生成器与运行逻辑分别位于对应包的generator/与index.js中可结合 docs/core-plugins 下的文档进一步了解。总结Vue CLI 的配置体系可以分为三个层次全局 CLI 配置.vuerc/vue config、项目级配置vue.config.js或package.json的vue字段推荐前者、以及各工具链独立配置babel.config.js、.eslintrc、tsconfig.json、Jest/Mocha 与 E2E 插件。理解 options.js 中的默认值与校验规则、Service.js 中的加载与合并流程以及 config 目录 下各内置插件对选项的消费方式是深入掌握 Vue CLI 构建行为的关键。遇到不确定的配置结果时随时可以使用vue inspect查看解析后的完整 webpack 配置确认每个选项的真实生效情况。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vue CLI 配置完全指南：从 vue.config.js 到全局 CLI 设置
Vue CLI 配置完全指南从 vue.config.js 到全局 CLI 设置【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli本篇技术指南围绕 Vue CLIwebpack-based tooling for Vue.js Development的配置体系展开覆盖全局 CLI 配置.vuerc与vue config命令、vue.config.js中全部核心选项部署路径、多页面、Lint、CSS、devServer 代理、Webpack 定制等以及 Babel / ESLint / TypeScript 与测试工具链的配置方式。阅读本文后你将掌握 Vue CLI 配置的完整脉络并能结合实际源码理解每个选项背后的生效机制从容应对各类构建与部署场景。全局 CLI 配置vue/cli的一些全局设置——例如偏好的包管理器packageManager、本地保存的 presetpresets——存储在用户主目录下的 JSON 文件.vuerc中。你可以用任意编辑器直接修改该文件来调整已保存的选项。除了手工编辑更推荐使用vue config命令来查看或修改全局 CLI 配置。该命令的实现位于 packages/vue/cli/lib/config.js支持以下子命令子命令作用vue config打印.vuerc文件解析路径与完整内容JSON 格式化vue config --get key读取指定键的值如vue config --get packageManagervue config --set key value写入指定键源码中会自动把纯数字字符串转为整数、把true/false转为布尔值vue config --delete key删除指定键vue config --edit用系统默认编辑器打开.vuercvue config --json以 JSON 形式输出供脚本消费输出包含resolvedPath与content等字段目标浏览器browserslistVue CLI 使用browserslist配置来确定项目需要转译的 JavaScript 特性与需要添加的 CSS 厂商前缀。你可以在package.json的browserslist字段或独立的.browserslistrc文件中声明目标浏览器范围。该值会被babel/preset-env与autoprefixer消费具体机制详见 docs/guide/browser-compatibility.md。默认的 Vue CLI 项目通过vue/babel-preset-app使用babel/preset-env并默认传入useBuiltIns: usage即按源码实际用到的语言特性自动注入最小化 polyfill 集合。需要说明的是这意味着一部分第三方依赖自身的 polyfill 需求无法被自动检测——当依赖需要 polyfill 时可以显式配置vue/babel-preset-app的polyfills选项或在入口文件中使用useBuiltIns: entry并引入core-js/stable等方式解决。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 { // 配置项... }也可以使用vue/cli-service提供的defineConfig帮助函数以获得更好的类型提示IntelliSense支持// vue.config.js const { defineConfig } require(vue/cli-service) module.exports defineConfig({ // 配置项... })defineConfig的实现位于 packages/vue/cli-service/lib/Service.js本质上只是原样返回传入的配置对象用于获得类型标注支持。配置文件加载与合并的源码机制从源码可以更清楚地看到配置的完整生命周期。在 packages/vue/cli-service/lib/util/loadFileConfig.js 中配置文件的查找顺序是process.env.VUE_CLI_SERVICE_CONFIG_PATH环境变量指定路径./vue.config.js./vue.config.cjs./vue.config.mjs并且会根据is-file-esm的检测结果决定用import()还是require()加载因此 ESM 与 CJS 风格的配置文件都被支持。在 packages/vue/cli-service/lib/util/resolveUserConfig.js 中确定了三者的优先级vue.config.js文件配置 package.json的vue字段 内联选项inlineOptions。若同时存在文件配置与vue字段后者会被忽略并给出迁移警告。该模块还会做两项规范化处理publicPath末尾自动补/除非是auto并去掉开头的./前缀outputDir末尾的多余斜杠会被移除。随后配置会交给 packages/vue/cli-service/lib/options.js 中定义的 Joi schema 做校验任何非法值都会在启动时报错。在 packages/vue/cli-service/lib/Service.js 中加载到的用户配置会通过defaultsDeep(loadedUserOptions, defaults())与默认值深度合并再依次应用内置插件与chainWebpack/configureWebpack回调。部署与输出路径相关选项baseUrl已废弃自 Vue CLI 3.3 起请改用publicPath。publicPath类型string默认值/应用构建产物将要部署的基准 URLVue 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/则应设置为/my-app/。值也可以是空字符串或相对路径./此时所有资源将使用相对路径引用适合部署到任意公共目录或用于 Cordova 混合应用这类基于文件系统的环境。::: warning 相对 publicPath 的限制 使用相对publicPath时需注意以下场景应避免使用 HTML5history.pushState路由使用pages选项构建多页面应用MPA。 :::该值在开发阶段同样生效。若希望开发服务器从根路径提供服务可以按环境条件取值module.exports { publicPath: process.env.NODE_ENV production ? /production-sub-path/ : / }在源码层面publicPath通过 packages/vue/cli-service/lib/config/base.js 写入 webpack 的output.publicPath同时 packages/vue/cli-service/lib/Service.js 中还有一道守卫构建目标非app时若检测到output.publicPath与projectOptions.publicPath不一致会直接抛出错误提示改用vue.config.js中的publicPath。outputDir类型string默认值dist运行vue-cli-service build时生产构建产物的输出目录。注意每次构建前该目录会被清空可通过--no-clean参数关闭此行为。::: tip 始终使用outputDir而不要修改 webpack 的output.path。 :::assetsDir类型string默认值用于存放生成的静态资源js、css、img、fonts的目录相对outputDir。::: tip 当覆盖了生成资源的filename或chunkFilename时assetsDir会被忽略。 :::indexPath类型string默认值index.html生成的index.html的输出路径相对outputDir也可以指定绝对路径。在 packages/vue/cli-service/lib/config/app.js 中可以看到当indexPath不是默认值时Vue CLI 会借助内置的MovePlugin把构建生成的index.html移动到目标位置。filenameHashing类型boolean默认值true默认情况下生成的静态资源文件名会包含内容哈希contenthash便于缓存管理。但这一行为依赖 Vue CLI 自动生成的index.html若你无法使用 CLI 生成的 HTML可以将此选项设为false以关闭文件名哈希。源码中哈希格式为js/[name].[contenthash:8].js与css/[name].[contenthash:8].css参见 packages/vue/cli-service/lib/config/app.js 与 packages/vue/cli-service/lib/config/css.js。pages多页面应用MPA类型Object默认值undefined以多页面模式构建应用。每个「页面」都应有对应的 JavaScript 入口文件。值是一个对象键为入口名称值可以是一个对象可指定entry、template、filename、title与chunks除entry外均可选。这些属性之外的其他属性会被原样传给html-webpack-plugin用于更精细地定制该插件或一个字符串直接指定其entry。module.exports { pages: { index: { // 页面入口 entry: src/index/main.js, // 源模板 template: public/index.html, // 输出为 dist/index.html filename: index.html, // 使用 title 选项时模板中的 title 需写成 // title% htmlWebpackPlugin.options.title %/title title: Index Page, // 该页面引入的 chunks默认是 // 抽出的公共 chunk 与 vendor chunk chunks: [chunk-vendors, chunk-common, index] }, // 使用仅入口的字符串格式时 // 模板会被推断为 public/subpage.html // 若不存在则回退到 public/index.html。 // 输出文件名被推断为 subpage.html。 subpage: src/subpage/main.js } }::: tip 在多页面模式下webpack 配置会包含多个html-webpack-plugin与preload-webpack-plugin实例。如果你要修改这些插件的配置请先用vue inspect检查实际配置。 :::从源码看packages/vue/cli-service/lib/config/app.js 会清空默认入口遍历pages中的每个页面字符串格式会被归一化为{ entry: c }entry支持字符串或数组数组会逐一api.resolve后合并进该入口模板按public/name.html推断不存在时回退到public/index.html再回退到内置默认模板每个页面生成独立的html-name插件实例。默认的chunks为[chunk-vendors, chunk-common, name]与文档中的示例一致。开发与代码质量选项lintOnSave类型boolean | warning | default | error默认值default是否在开发过程中保存文件时执行 lint。该选项仅在安装了vue/cli-plugin-eslint时生效。值为true或warning时lint 错误会作为警告输出。默认警告只打印到终端、不会中断编译因此是适合开发的默认行为值为default时lint 错误会真正作为错误上报从而显示在浏览器 overlay 中同时 lint 错误会导致编译失败值为error时lint 警告也会被当作错误处理同样显示在 overlay 中。也可以在devServer.overlay中配置同时展示警告与错误// vue.config.js module.exports { devServer: { overlay: { warnings: true, errors: true } } }当lintOnSave为真值时eslint 会在开发与生产构建中都生效若只想在开发阶段启用可以这样配置// vue.config.js module.exports { lintOnSave: process.env.NODE_ENV ! production }源码实现位于 packages/vue/cli-plugin-eslint/index.jstreatAllAsWarnings lintOnSave true || lintOnSave warning、treatAllAsErrors lintOnSave error并由此推导出failOnWarning与failOnError传入eslint-webpack-plugin最终通过webpackConfig.plugin(eslint)挂载。该插件还基于 ESLint 版本与package.json内容生成缓存标识避免升级 ESLint 插件后使用过期缓存。runtimeCompiler类型boolean默认值false是否使用包含模板编译器的 Vue 构建版本。设为true后可以在 Vue 组件中使用template选项但会为应用额外增加约 10KB 的体积。这与「Runtime Compiler vs. Runtime-only」的取舍有关默认的 runtime-only 构建体积更小但无法在运行时编译模板字符串。transpileDependencies类型boolean | Arraystring | RegExp默认值false默认情况下babel-loader会忽略node_modules内的所有文件。如果第三方依赖包含未被转译的代码可以通过此选项启用转译。转译全部依赖会拖慢构建因此更推荐传入包名或名称模式组成的数组只显式转译个别依赖。在 packages/vue/cli-service/lib/options.js 中该选项的 schema 允许boolean或数组。::: warning Jest 配置说明 该选项不被cli-unit-jest插件支持在 Jest 中除非依赖使用了非标准特性否则无需转译node_modules中的代码Node 8.11 已支持最新的 ECMAScript 特性。若依赖使用了 ES6import/export语法需要转换请在jest.config.js中使用transformIgnorePatterns选项。更多信息见 docs/core-plugins/unit-jest.md。 :::productionSourceMap类型boolean默认值true源码中为!process.env.VUE_CLI_TEST测试环境下自动关闭生产构建是否需要 source map。如果不需要生产环境的 source map设为false可以加快生产构建速度。源码默认值见 packages/vue/cli-service/lib/options.js。HTML 标签安全与完整性crossorigin类型string默认值undefined为生成的 HTML 中link relstylesheet与script标签配置crossorigin属性。注意仅影响html-webpack-plugin注入的标签直接写在源模板public/index.html里的标签不受影响。schema 中允许的取值为、anonymous、use-credentials见 packages/vue/cli-service/lib/options.js。integrity类型boolean默认值false设为true可为生成的 HTML 中link与script标签启用 Subresource IntegritySRI。当构建产物托管在 CDN 上时推荐开启以增强安全性。同样只影响html-webpack-plugin注入的标签。另外启用 SRI 后preload 资源提示会被禁用——这是为了规避 Chrome 中导致资源被下载两次的已知缺陷Chromium issue 677022。crossorigin与integrity在源码中由内置的CorsPlugin实现见 packages/vue/cli-service/lib/config/app.js 与 packages/vue/cli-service/lib/webpack/CorsPlugin.js。定制 Webpack 配置configureWebpack类型Object | Function值为对象时会通过webpack-merge合并进最终配置值为函数时函数会接收解析后的最终配置作为参数可以原地修改配置而不返回任何值或返回一份克隆/合并后的新配置。在 packages/vue/cli-service/lib/Service.js 的resolveWebpackConfig中可以看到函数形式下返回值非空时执行merge(config, res)字面量形式下执行merge(config, fn)。注意合并后会通过cloneRuleNames恢复webpack-chain注入的__ruleNames信息以保证vue inspect正常工作。更多用法可参考 docs/guide/webpack.md。chainWebpack类型Function函数会接收一个由webpack-chain提供的ChainableConfig实例从而对内部 webpack 配置进行更细粒度的链式修改。这是比configureWebpack更进阶的定制方式适合需要精确控制 loader 规则、插件实例等场景。用法见 docs/guide/webpack.md。在 packages/vue/cli-service/lib/Service.js 中用户配置的chainWebpack会被推入webpackChainFns随后在resolveChainableWebpackConfig中依次应用到webpack-chain的Config实例上。CSS 相关选项css.modules已废弃自 v4 起废弃请改用css.requireModuleExtension。在 v3 中它是css.requireModuleExtension的取反。需要说明的是在当前仓库版本v5中这两个选项均已从 packages/vue/cli-service/lib/options.js 的 schema 中移除——CSS Modules 统一通过*.module.[ext]文件名约定识别。css.requireModuleExtension类型boolean默认值true默认情况下只有以*.module.[ext]结尾的文件才被当作 CSS Modules 处理。设为false后可以去掉文件名中的.module让所有*.(css|scss|sass|less|styl(us)?)文件都被当作 CSS Modules。::: tip 若在css.loaderOptions.css中配置了 CSS Modules 相关参数则css.requireModuleExtension必须显式指定为true或false否则无法确定这些参数是否应作用于所有 CSS 文件。 :::从源码看packages/vue/cli-service/lib/config/css.js 为每种样式语言创建了四条oneOf规则vue-modulesstyle module、vue普通style、normal-modules*.module.*文件与normal普通 CSS 导入style module与*.module.*会强制开启 CSS Modulesmodules.auto: () true。更多信息见 docs/guide/css.md。css.extract类型boolean | Object默认值production 下为truedevelopment 下为false是否把组件中的 CSS 抽取到独立的 CSS 文件而不是内联进 JavaScript 动态注入。注意构建 Web Components 时该选项始终被关闭样式会内联进 shadowRoot构建库library时也可设为false避免使用方必须自行引入 CSS开发模式下默认关闭抽取因为它与 CSS 热重载不兼容显式设为true可以强制始终抽取除true外也可以传入一个对象作为mini-css-extract-plugin的配置项。源码中extract的默认值即isProdextract isProd抽取时通过mini-css-extract-plugin输出css/[name].[contenthash:8].css并用css-minimizer-webpack-plugin做压缩不抽取时使用vue-style-loader注入样式且生产环境会额外用cssnano对内联样式做压缩见 packages/vue/cli-service/lib/config/css.js。css.sourceMap类型boolean默认值false是否启用 CSS 的 source map。设为true可能影响构建性能。css.loaderOptions类型Object默认值{}向 CSS 相关的 loader 传递配置。例如module.exports { css: { loaderOptions: { css: { // 这些选项会传给 css-loader }, postcss: { // 这些选项会传给 postcss-loader } } } }支持的 loader 包括css-loader、postcss-loader、sass-loader、less-loader、stylus-loader。还可以通过scss选项单独配置scss语法与sass区分。schema 见 packages/vue/cli-service/lib/options.js。::: tip 这种方式优于通过chainWebpack手工修改具体 loader因为相关 loader 可能在多处使用这些参数需要被统一应用。源码中loaderOptions会合并进css-loader含sourceMap、importLoaders计算等、postcss-loader以及各预处理器 loader 的 options 中详见 packages/vue/cli-service/lib/config/css.js。 :::另外值得一提的是源码会在项目缺少有效 PostCSS 配置时自动注入autoprefixer作为默认插件并做 PostCSS 版本预检见 packages/vue/cli-service/lib/config/css.js。devServer 与开发代理devServer类型Objectwebpack-dev-server的所有选项均受支持但需注意两点部分值如host、port、https可能被命令行参数覆盖部分值如publicPath、historyApiFallback不应被修改它们必须与publicPath保持同步开发服务器才能正常工作。devServer.proxy类型string | Object当前端应用与后端 API 服务不在同一主机上时需要在开发阶段代理 API 请求可通过devServer.proxy配置。可以传一个字符串指向开发 API 服务器module.exports { devServer: { proxy: http://localhost:4000 } }这会让开发服务器把所有未知请求未匹配到静态文件的请求代理到http://localhost:4000。::: warningdevServer.proxy使用字符串形式时只会代理 XHR 请求。要测试 API URL请不要直接在浏览器中打开而是使用 API 调试工具如 Postman。 :::如需更精细地控制代理行为可以使用path: options键值对的对象形式完整的选项列表可参考http-proxy-middlewaremodule.exports { devServer: { proxy: { ^/api: { target: url, ws: true, changeOrigin: true }, ^/foo: { target: other_url } } } }devServer.inline类型boolean默认值true在开发服务器的两种工作模式间切换iframe mode无需额外配置浏览器访问http://host:port/webpack-dev-server/path即可调试应用页面顶部会出现通知栏inline mode直接访问http://host:port/path调试应用构建消息显示在浏览器控制台中。构建性能与扩展选项parallel类型boolean | number默认值require(os).cpus().length 1机器多于 1 个 CPU 核心时启用是否使用thread-loader并行转译 Babel 或 TypeScript。生产构建在系统多于 1 个 CPU 核心时默认启用传入数字可指定使用的 worker 数量。源码中hasMultipleCores()还做了防御性处理cpus()可能返回 undefined见 packages/vue/cli-service/lib/options.js。::: warning 不要将parallel与不可序列化的 loader 选项如正则、日期、函数组合使用。这些选项无法正确传给相应 loader可能导致意外错误。 :::pwa类型Object传递给 PWA 插件的配置对应vue/cli-plugin-pwa。用于定制 Service Worker 与 Web App Manifest 等行为。pluginOptions类型Object该对象不经过任何结构校验因此可以用于向第三方插件传递任意参数。例如module.exports { pluginOptions: { foo: { // 插件可以通过 options.pluginOptions.foo 访问这些设置 } } }在 packages/vue/cli-service/lib/options.js 中它以joi.object()定义不做内部约束第三方插件在apply阶段从projectOptions.pluginOptions中读取。工具链配置Babel、ESLint 与 TypeScriptBabelBabel 通过babel.config.js配置。::: tip Vue CLI 使用 Babel 7 的新配置格式babel.config.js。与.babelrc或package.json中的babel字段不同该配置文件不基于文件位置解析而是对项目根目录下的所有文件包括node_modules中的依赖一致生效。在 Vue CLI 项目中建议始终使用babel.config.js而非其他格式。 :::所有 Vue CLI 应用都使用vue/babel-preset-app它内置了babel-preset-env、JSX 支持以及为最小化打包体积优化的配置具体实现见 packages/vue/babel-preset-app/index.js。Polyfill 相关策略参见 docs/guide/browser-compatibility.md。ESLintESLint 通过.eslintrc或package.json的eslintConfig字段配置插件实现见 packages/vue/cli-plugin-eslint含 index.js、eslintOptions.js 与 prompts.js。TypeScriptTypeScript 通过tsconfig.json配置插件实现见 packages/vue/cli-plugin-typescript含 tsconfig.json 生成逻辑。测试工具链配置单元测试Jest详见 packages/vue/cli-plugin-unit-jest预置配置位于 packages/vue/cli-plugin-unit-jest/jest-preset.jsMocha通过mocha-webpack详见 packages/vue/cli-plugin-unit-mocha。E2E 测试Cypress详见 packages/vue/cli-plugin-e2e-cypressNightwatch详见 packages/vue/cli-plugin-e2e-nightwatchWebdriverIO详见 packages/vue/cli-plugin-e2e-webdriverio。各测试插件的生成器与运行逻辑分别位于对应包的generator/与index.js中可结合 docs/core-plugins 下的文档进一步了解。总结Vue CLI 的配置体系可以分为三个层次全局 CLI 配置.vuerc/vue config、项目级配置vue.config.js或package.json的vue字段推荐前者、以及各工具链独立配置babel.config.js、.eslintrc、tsconfig.json、Jest/Mocha 与 E2E 插件。理解 options.js 中的默认值与校验规则、Service.js 中的加载与合并流程以及 config 目录 下各内置插件对选项的消费方式是深入掌握 Vue CLI 构建行为的关键。遇到不确定的配置结果时随时可以使用vue inspect查看解析后的完整 webpack 配置确认每个选项的真实生效情况。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
