Vue CLI 的 CLI Service 全指南：vue-cli-service 命令体系、配置方式与源码级原理

Vue CLI 的 CLI Service 全指南vue-cli-service 命令体系、配置方式与源码级原理【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-clivue/cli-service是 Vue CLI 项目中的本地构建服务它把 webpack、webpack-dev-server、Babel、TypeScript 等工具链封装成一个名为vue-cli-service的统一命令入口。本文以官方指南docs/guide/cli-service.md为骨架结合本仓库源码packages/vue/cli-service系统讲解serve、build、inspect、help等核心命令的参数与用法、--skip-plugins的插件跳过机制、缓存与并行编译策略、Git Hooks 以及免 eject 的配置体系让你既能熟练上手日常开发也能理解命令背后 Service 的运行机制。认识 vue-cli-service项目内的构建服务二进制在任何一个 Vue CLI 创建的项目中vue/cli-service都会安装一个名为vue-cli-service的二进制文件。二进制的入口定义在 packages/vue/cli-service/package.json 的bin字段中指向bin/vue-cli-service.js。你既可以在 npm scripts 中直接以vue-cli-service的方式调用它也可以从终端使用./node_modules/.bin/vue-cli-service访问。使用默认 preset 创建的项目其package.json中通常会出现以下 scripts{ scripts: { serve: vue-cli-service serve, build: vue-cli-service build } }随后即可用 npm 或 Yarn 触发npm run serve # OR yarn serve如果你安装了 npx现代版本 npm 自带的工具还可以直接调用npx --no vue-cli-service serve从源码结构看vue-cli-service的核心是 packages/vue/cli-service/lib/Service.js 中定义的Service类。它负责在init()阶段加载环境变量Service.js#L101-L142、读取用户配置、按顺序应用所有插件内置插件与项目依赖中形如vue/cli-plugin-*的插件见 Service.js#L169-L235然后在run()中根据命令名找到注册好的命令并执行Service.js#L237-L263。每个命令的默认模式如 serve 默认development、build 默认production由插件通过module.exports.defaultModes暴露Service 在应用插件之前就能解析出来。::: tip 你还可以通过vue ui命令打开图形化界面用 GUI 运行脚本并使用额外功能例如下面即将讲到的 Webpack Analyzer。 :::vue-cli-service serve本地开发服务器serve命令用于启动开发服务器其完整用法如下Usage: vue-cli-service serve [options] [entry] Options: --open open browser on server start --copy copy url to clipboard on server start --mode specify env mode (default: development) --host specify host (default: 0.0.0.0) --port specify port (default: 8080) --https use https (default: false) --public specify the public network URL for the HMR client --skip-plugins comma-separated list of plugin names to skip for this run这些参数的实际注册位于 packages/vue/cli-service/lib/commands/serve.js#L19-L32此外源码中还额外注册了--stdin当 stdin 结束时关闭服务参数。命令的默认模式为development见 serve.js#L395-L397。vue-cli-service serve基于 webpack-dev-server 启动开发服务器开箱即用地集成了热模块替换HMR源码改动后浏览器页面无需手动刷新即可局部更新。除命令行参数外你还可以通过vue.config.js中的 devServer 字段配置开发服务器例如代理、静态资源目录、客户端 overlay 等。从源码看项目级devServer选项会以更高优先级合并进 webpack 配置serve.js#L86-L89。关于几个值得注意的细节端口自动递增--port指定起始端口默认 8080源码通过portfinder在端口被占用时自动寻找下一个可用端口serve.js#L116-L117。--copy将本地开发服务器 URL 复制到剪贴板。复制成功时URL 旁边会显示(copied to clipboard)。少数平台可能不支持剪贴板操作。容器环境当检测到运行在 Docker、LXC 等容器中时源码通过/proc/1/cgroup检测见 serve.js#L366-L376HMR socket 无法自动推断公网地址终端会提示你显式配置devServer.public。history 回退开发服务器默认启用historyApiFallback并把config.pages中的多页配置转换为重写规则serve.js#L378-L393保证前端路由在刷新时也能正确回退到对应 HTML。关于 [entry] 参数的重要说明[entry]指的是入口文件默认是src/main.jsTypeScript 项目为src/main.ts而不是额外的入口文件。如果你在 CLI 中覆盖了 entry那么config.pages中的各页面入口将不再被考虑这可能导致报错。对应实现见 serve.js#L99-L105当传入 entry 时webpack 配置的入口会被直接替换为{ app: api.resolve(entry) }。vue-cli-service build生产构建build命令用于生成生产环境产物完整用法如下Usage: vue-cli-service build [options] [entry|pattern] Options: --mode specify env mode (default: production) --dest specify output directory (default: dist) --modern build app targeting modern browsers with auto fallback --target app | lib | wc | wc-async (default: app) --formats list of output formats for library builds (default: commonjs,umd,umd-min) --inline-vue include the Vue module in the final bundle of library or web component target --name name for lib or web-component mode (default: name in package.json or entry filename) --filename file name for output, only usable for lib target (default: value of --name), --no-clean do not remove the dist directory contents before building the project --report generate report.html to help analyze bundle content --report-json generate report.json to help analyze bundle content --skip-plugins comma-separated list of plugin names to skip for this run --watch watch for changes上述参数在 packages/vue/cli-service/lib/commands/build/index.js#L23-L41 中注册命令默认模式为productionbuild/index.js#L236-L238。vue-cli-service build会在dist/目录生成生产就绪的产物JS/CSS/HTML 全部经过压缩minify并自动进行 vendor 代码块拆分以利于缓存chunk manifest 会被内联进 HTML。有几个非常实用的参数值得展开--modern与现代模式Modern Mode现代模式为支持原生 ES2015 的现代浏览器提供原生代码包同时自动为旧浏览器回退到 legacy 包实现差异化加载differential loading。需要说明的是在本仓库当前的 5.x 实现中app 目标默认即启用差异化加载通过--no-module可以关闭对应源码中的--no-module选项见 build/index.js#L29。构建时会根据 browserslist 判断目标浏览器是否都已支持 ES module若全部支持则跳过双包构建build/index.js#L58-L67否则先构建 legacy 包再以子进程方式构建 modern 包build/index.js#L73-L91。详细背景可参考 浏览器兼容性指南 中的现代模式章节。--target允许将项目中的任意组件构建为库lib或 Web Componentswc、wc-async默认值为app。构建目标的分发逻辑见 build/index.js#L138-L148分别对应resolveLibConfig、resolveWcConfig与resolveAppConfig。官方文档中对应的 Build Targets 专题build-targets.md未收录于本仓库。--report/--report-json基于构建统计信息生成分析报告帮助分析 bundle 中包含的各模块体积。实现上通过webpack-bundle-analyzer的BundleAnalyzerPlugin完成build/index.js#L178-L193--report生成静态的report.html--report-json额外生成report.json统计文件。--dest指定输出目录默认值为options.outputDir即vue.config.js中的outputDir默认dist。构建前会先清空目标目录除非传入--no-cleanbuild/index.js#L195-L197。--watch监听文件变更并持续重建适合配合 CI 或静态服务器使用。注意在 watch 模式下默认模式会变为development见 Service.js#L241 的 mode 解析逻辑。vue-cli-service inspect检查 webpack 配置inspect命令用于查看 Vue CLI 项目内部的最终 webpack 配置完整用法Usage: vue-cli-service inspect [options] [...paths] Options: --mode specify env mode (default: development)实现位于 packages/vue/cli-service/lib/commands/inspect.js除了--mode之外源码还注册了这些实用参数--rule ruleName只查看某个特定的 module rule--plugin pluginName只查看某个特定的插件--rules列出所有 module rule 名称--plugins列出所有插件名称--verbose在输出中展示完整的函数定义--skip-plugins本次运行跳过的插件列表。例如npx --no vue-cli-service inspect --rules npx --no vue-cli-service inspect --rule vue npx --no vue-cli-service inspect module.rules关于配置调试的完整方法论可进一步阅读 webpack 指南 中的检查项目 webpack 配置章节。查看所有可用命令vue-cli-service help部分 CLI 插件会向vue-cli-service注入额外的命令。例如vue/cli-plugin-eslint会注入vue-cli-service lint命令。查看所有已注入的命令npx --no vue-cli-service help查看某个命令的具体选项npx --no vue-cli-service help [command]从源码看help命令由 packages/vue/cli-service/lib/commands/help.js 实现不带参数时遍历api.service.commands列出所有命令及描述help.js#L14-L34带命令名时则展示该命令注册的usage、options等元信息。这些元信息来自插件调用api.registerCommand(name, opts, fn)时传入的选项对象PluginAPI.js#L82-L88。跳过插件--skip-plugins--skip-plugins选项允许你在运行某个命令时排除指定的插件例如npx --no vue-cli-service build --skip-plugins pwa该选项对每一个vue-cli-service命令都可用包括其他插件自定义的命令。跳过多个插件时可以用逗号分隔也可以重复传入参数npx --no vue-cli-service build --skip-plugins pwa,apollo --skip-plugins eslint插件名称的解析规则与安装时一致参考 插件与 Preset 中的在已有项目中安装插件章节以下写法完全等价# these are all equivalent npx --no vue-cli-service build --skip-plugins pwa npx --no vue-cli-service build --skip-plugins vue/pwa npx --no vue-cli-service build --skip-plugins vue/cli-plugin-pwa从源码看该逻辑由 Service.js#L144-L167 的setPluginsToSkip实现它解析所有--skip-plugins出现将每个值按逗号拆分并通过resolvePluginId归一化为插件 ID存入pluginsToSkip集合随后init()在应用插件时会跳过集合中的插件Service.js#L80-L83。缓存与并行编译为了加速编译CLI Service 内置了两项优化cache-loaderVue、Babel、TypeScript 的编译默认启用cache-loader缓存。缓存文件存放在node_modules/.cache目录下。如果遇到奇怪的编译问题建议先删除该缓存目录再重试。在 packages/vue/cli-service/lib/config/base.js 中Vue 2 与 Vue 3 项目的vue-loader规则都会在 loader 链最前面插入 cache-loader并使用api.genCacheConfig()基于 CLI 版本、NODE_ENV、相关配置文件内容等生成缓存标识PluginAPI.js#L151-L214。thread-loader当机器 CPU 核心数大于 1 时Babel/TypeScript 的转译会启用thread-loader进行多线程并行处理进一步缩短构建时间。Git Hooks用 gitHooks 字段配置钩子安装vue/cli-service时它还会顺带安装 yorkie一个 husky 的 fork使你可以直接在package.json的gitHooks字段中声明 Git 钩子{ gitHooks: { pre-commit: lint-staged }, lint-staged: { *.{js,vue}: vue-cli-service lint } }上面的示例会在每次pre-commit时通过lint-staged对暂存的.js/.vue文件执行vue-cli-service lint实现提交前的自动代码检查。::: warning yorkie 是 husky 的 fork二者互不兼容如果你的项目同时安装了 husky可能会出现钩子失效或行为冲突。 :::免 eject 的配置体系通过vue create创建的项目开箱即用无需额外配置各插件被设计为彼此协作大多数情况下你只需在交互式提示中选择所需的功能即可。但 Vue CLI 也深知无法满足所有需求且项目需求会随时间变化因此它允许你无需 eject就能配置工具链的几乎每个方面在vue.config.js中使用devServer、outputDir、publicPath、pages等顶层字段调整行为注意构建目标非 app 时源码会阻止直接修改 webpack 的output.publicPath要求统一走publicPath配置项见 Service.js#L301-L312通过chainWebpack函数以链式 API 细粒度修改 webpack 配置通过configureWebpack提供配置对象或函数以 merge 方式合并进最终配置两类回调的收集与合并见 Service.js#L265-L334。完整的配置项说明请查阅 Config Reference。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考