Vue CLI是Vue官方提供的一套标准化项目脚手架工具，能够快速生成带有完整工程化配置的项目骨架。相比手动搭建Webpack环境，使用Vue CLI可以节省大量时间，同时保证项目结构规范、配置统一。本文将从安装、项目创建、核心配置、常见问题四个方面，详细讲解Vue CLI的使用方法和避坑技巧，帮助你一次性掌握这套工具。
一、Vue CLI的安装与前置准备
安装Vue CLI之前，首先要确认本机的Node.js版本。Vue CLI 4.x要求Node 8.9以上，而Vue CLI 5.x要求Node 12.0以上，推荐使用LTS长期支持版本。可以通过下面的命令检查版本：
node -v npm -v
确认Node版本没问题后，使用npm全局安装Vue CLI。安装命令很简单，一行即可完成：
npm install -g @vue/cli # 或者使用yarn安装 yarn global add @vue/cli
安装完成后，执行vue --version查看版本号。如果命令能正常输出版本，说明安装成功。如果提示vue不是内部或外部命令，通常是全局安装路径没有加入系统环境变量导致的，Windows用户可以在npm的全局安装目录中找到vue.cmd文件，把对应路径加入PATH即可解决。
这里有一个常见的坑需要提前说明：如果之前安装过旧版本的vue-cli（2.x版本），包名是vue-cli而不是@vue/cli，两者会冲突。需要先执行npm uninstall -g vue-cli卸载旧包，再安装新版本，否则执行vue create时会报错。
二、使用vue create创建项目的完整流程
安装好脚手架后，进入你想存放项目的目录，执行创建命令：
vue create my-project
执行后命令行会给出几个选项。第一项是默认预设（Default preset），包含Babel和ESLint，适合快速开始；第二项是手动选择特性（Manually select features），推荐有经验的开发者选择这一项，可以自由挑选需要的模块。
手动模式下可选的特性包括：Babel转译、TypeScript支持、PWA渐进式应用、Vue Router路由、Vuex或Pinia状态管理、CSS预处理器、Linter代码检查以及单元测试和端到端测试框架。选择时用方向键移动，空格键勾选或取消，回车确认。一个典型的中小型项目通常选择Babel、Router、Vuex、CSS Pre-processors和Linter这几项就够了。
接下来CLI会追问一系列细节问题，比如是否使用history模式路由、选择哪种CSS预处理器（Sass或Less）、ESLint的规则等级、配置文件是放在独立文件还是package.json中等。全部回答完成后，CLI会询问是否把这个选择保存为preset预设。保存后下次创建项目可以直接复用，团队协作时也能保证配置统一，这个功能非常实用。
创建完成后，进入项目目录并启动开发服务器：
cd my-project npm run serve
浏览器打开命令行提示的地址（默认是http://localhost:8080），看到Vue的欢迎页面就说明项目搭建成功了。
三、vue.config.js核心配置详解
Vue CLI 3以后，Webpack的复杂配置被封装起来了，开发者只需在项目根目录创建一个vue.config.js文件，通过简洁的配置项就能覆盖默认行为。下面是一个包含常用配置的完整示例：
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
// 部署在子路径时需要修改，例如部署到 /app/ 目录下
publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
// 打包输出目录
outputDir: 'dist',
// 开发服务器配置
devServer: {
port: 8080,
open: true,
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
pathRewrite: { '^/api': '' }
}
}
},
// 路径别名
configureWebpack: {
resolve: {
alias: {
'@': require('path').resolve(__dirname, 'src')
}
}
}
})其中proxy代理配置是前后端联调时最常用的功能。开发环境下浏览器存在同源策略限制，前端页面跑在8080端口，后端接口在3000端口，直接请求会报跨域错误。通过上面的代理配置，所有以api开头的请求会被转发到3000端口，并且pathRewrite会把前缀去掉，后端收到的就是干净的接口路径。
路径别名同样重要。默认情况下CLI已经提供了@指向src目录的别名，代码中写import HelloWorld from '@/components/HelloWorld.vue'比一长串相对路径清晰得多。如果项目层级较深，还可以追加更多别名，例如把@views指向src/views目录。
打包优化方面，可以在configureWebpack中配置splitChunks拆分第三方依赖，或者通过chainWebpack做更精细的修改。同时建议在package.json中把现代模式生产构建命令加上，打包时会生成兼容旧浏览器的版本和现代版本，减少体积。
四、常见报错与避坑建议
第一类常见问题是安装缓慢或失败。npm默认源在国内访问不稳定，建议切换为国内镜像源，例如执行npm config set registry https://registry.npmmirror.com。如果项目依赖安装到一半卡住，可以删除node_modules目录和package-lock.json文件后重新安装。
第二类问题是ESLint报错过多导致编译失败。新手经常被满屏的缩进、分号错误困扰。可以在创建项目时选择基本配置规则，或者在项目运行时执行vue ui打开图形化管理界面，在插件管理里调整Lint规则。如果确实不想要强校验，也可以在vue.config.js中设置lintOnSave: false关闭保存时检查。
第三类问题是Node版本过高导致的依赖报错。Node 17以上版本改变了OpenSSL的默认行为，一些旧项目启动时会报digital envelope routines::unsupported错误。解决办法是使用nvm切换到Node 16，或者临时设置环境变量NODE_OPTIONS为--openssl-legacy-provider再启动项目。
最后还有一些实用建议：善用vue ui图形化界面管理项目，比命令行更直观；使用vue inspect命令可以查看最终的Webpack完整配置，方便排查问题；团队项目中把预设保存成远程preset或者放到代码仓库中共享，避免每个人配置不一致。掌握了这些内容，Vue CLI基本就能用得得心应手了。