VueCLI3.X安装与配置全攻略-编程阁

一、Vue CLI 3.X 脚手架安装与使用

1. 安装前提

- 确保已安装 Node.js 8.9+（推荐 10+ 版本），终端输入 node -v 验证版本。

- 若未安装 Node.js，前往 Node.js 官网下载对应系统版本（建议勾选“Add to PATH”自动配置环境变量）。

2. 全局安装 Vue CLI

打开终端（Windows cmd/PowerShell，Mac/Linux 终端），执行以下命令：

bash

# 卸载旧版本（若曾安装 Vue CLI 2.X）

npm uninstall -g vue-cli

# 安装 Vue CLI 3.X（推荐 npm，也可使用 yarn）

npm install -g @vue/cli

# 验证安装成功（显示版本号即正常）

vue --version 或 vue -V

3. 创建 Vue 项目

方法 1：命令行创建（基础方式）

bash

# 1. 执行创建命令，替换 <project-name> 为项目名称（英文，不含空格）

vue create <project-name>

# 2. 选择项目模板（上下键切换，回车确认）

# - Default ([Vue 2] babel, eslint)：Vue 2 基础模板（快速上手）

# - Default (Vue 3) ([Vue 3] babel, eslint)：Vue 3 基础模板

# - Manually select features：自定义模板（推荐，可选择路由、Vuex 等）

# 3. 自定义模板选择（按空格勾选/取消，回车下一步）

# 必选：Babel（ES6 转 ES5）、ESLint（代码语法检查）

# 常用可选：Router（路由）、Vuex（状态管理）、CSS Pre-processors（CSS 预处理器，如 Less/Sass）、Unit Testing（单元测试）

# 4. 后续配置（根据选择的功能弹出，按需求选择）

# - 选择 Vue 版本（Vue 2 或 Vue 3）

# - 是否使用 history 模式的路由（是则输入 Y，否则 N，默认 hash 模式）

# - 选择 CSS 预处理器（Less/Sass/SCSS/Stylus，推荐 Less）

# - 选择 ESLint 配置（推荐 Standard 或 Airbnb）

# - 选择 ESLint 校验时机（保存时/提交时，推荐保存时）

# - 选择配置文件存放位置（单独文件/ package.json 中，推荐单独文件）

# - 是否保存为预设模板（后续创建项目可复用，输入 Y/N）

# 5. 等待依赖安装完成（网络慢可切换 npm 镜像：npm config set registry https://registry.npm.taobao.org）

方法 2：图形化界面创建（可视化操作）

bash
# 1. 启动 Vue CLI 图形化工具
vue ui
# 2. 浏览器自动打开 http://localhost:8000，点击“创建”→ 选择项目存放目录 → 输入项目名称 → 点击“下一步”
# 3. 选择模板（同命令行，基础/自定义）→ 配置项目功能 → 点击“创建项目”
4. 运行/打包项目
bash
# 1. 进入项目目录
cd <project-name>
# 2. 启动开发服务器（默认端口 8080，浏览器访问 http://localhost:8080）
npm run serve
# 3. 打包生产环境（生成 dist 目录，用于部署）
npm run build
# 4. 代码校验（修复 ESLint 错误）
npm run lint

二、Vue CLI 插件的使用方法

Vue CLI 插件是扩展项目功能的核心（如路由、Vuex、UI 库等），支持安装/卸载/更新，分为官方插件（@vue/cli-plugin-xxx）和第三方插件（如 vue-cli-plugin-element）。

1. 安装插件（3 种方式）

方式 1：命令行安装（推荐）

bash
# 进入项目目录后执行，替换 <plugin-name> 为插件名称
vue add <plugin-name>
# 示例 1：安装官方路由插件（已创建项目无路由时）
vue add router
# 示例 2：安装官方 Vuex 插件
vue add vuex
# 示例 3：安装第三方插件（如 Element UI）
vue add element

方式 2：图形化界面安装

1. 启动图形化工具： vue ui

2. 进入已创建的项目 → 点击左侧“插件” → 点击“添加插件”

3. 搜索插件名称（如 router、element）→ 选择插件 → 点击“安装” → 按提示配置

方式 3：npm/yarn 安装（适用于非 Vue CLI 官方插件）

bash
# 安装插件（如 axios）
npm install axios --save
# 在项目中直接引入使用（main.js 中全局引入或组件内局部引入）
import axios from 'axios'
Vue.prototype.$axios = axios // 全局挂载

2. 卸载插件

bash
# 命令行卸载（替换 <plugin-name> 为插件名称）
npm uninstall <plugin-name>
# 示例：卸载 Element UI 插件
npm uninstall element-ui

3. 常用官方插件

- @vue/cli-plugin-babel ：ES6 转 ES5（默认安装）

- @vue/cli-plugin-eslint ：代码语法检查（默认安装）

- @vue/cli-plugin-router ：路由管理

- @vue/cli-plugin-vuex ：状态管理

- @vue/cli-plugin-css-preprocessors ：CSS 预处理器支持

三、vue.config.js 文件配置（核心）

vue.config.js 是 Vue CLI 3.X 的全局配置文件（需手动在项目根目录创建），用于覆盖默认配置（如端口、代理、打包路径等）。

1. 基础配置模板（常用配置合集）

javascript
module.exports = {
// 1. 开发服务器配置（npm run serve 时生效）
devServer: {
port: 8081, // 自定义开发端口（默认 8080）
open: true, // 启动后自动打开浏览器
host: '0.0.0.0', // 允许局域网访问（如手机访问电脑 IP:8081）
proxy: { // 跨域代理配置（解决开发环境跨域问题）
'/api': { // 匹配所有以 /api 开头的请求路径
target: 'http://localhost:8080', // 目标服务器地址（后端接口地址）
changeOrigin: true, // 开启跨域
pathRewrite: { // 路径重写（可选，根据后端接口调整）
'^/api': '' // 去掉请求路径中的 /api（如 /api/user → /user）
}
}
}
},
// 2. 打包配置（npm run build 时生效）
outputDir: 'dist', // 打包输出目录（默认 dist）
assetsDir: 'static', // 静态资源（js/css/img）存放目录（默认 ''，即 dist 根目录）
indexPath: 'index.html', // 入口 HTML 文件路径（默认 index.html）
productionSourceMap: false, // 关闭生产环境 sourceMap（减少打包体积，加密源码）
// 3. CSS 相关配置
css: {
extract: true, // 生产环境是否提取 CSS 为单独文件（默认 true）
sourceMap: false, // 是否生成 CSS sourceMap（默认 false）
loaderOptions: { // CSS 预处理器配置（如 Less/Sass）
less: {
// 全局注入 Less 变量（无需在每个组件中 import）
additionalData: `@import "@/assets/style/variables.less";`
}
}
},
// 4. 插件配置
pluginOptions: {
// 第三方插件配置（如 vue-cli-plugin-element）
},
// 5. 其他配置
lintOnSave: process.env.NODE_ENV === 'development', // 仅开发环境开启 ESLint 校验
publicPath: './', // 打包后静态资源访问路径（本地打开 index.html 需配置为 ./，部署服务器可配置为 / 或域名）
}

2. 关键配置说明

- publicPath：核心配置，决定打包后静态资源的访问路径：

- 本地打开 dist/index.html：设置为 ./

- 部署到服务器根目录：设置为 /

- 部署到服务器子目录（如 http://xxx.com/my-project/ ）：设置为 /my-project/

- proxy：开发环境跨域必备，无需后端配置 CORS，直接通过代理转发请求。

四、环境变量与模式配置

Vue CLI 支持多环境配置（如开发/测试/生产），通过 .env 文件定义环境变量，实现不同环境下的配置隔离。

1. 环境文件创建（项目根目录）

文件名	环境模式	生效场景
.env	全局环境	所有环境都生效
.env.development	开发环境	npm run serve 时生效
.env.production	生产环境	npm run build 时生效
.env.test	测试环境	npm run test 时生效

2. 环境变量定义规则

- 变量名必须以 VUE_APP_ 开头（如 VUE_APP_BASE_API ），否则无法在项目中访问。

- 示例： .env.development 文件内容：

env
# 开发环境接口基础路径
VUE_APP_BASE_API = '/api'
# 开发环境是否开启调试模式
VUE_APP_DEBUG = true
- 示例： .env.production 文件内容：
env
# 生产环境接口基础路径（真实后端地址）
VUE_APP_BASE_API = 'http://www.xxx.com/api'
# 生产环境关闭调试模式
VUE_APP_DEBUG = false

3. 在项目中使用环境变量

- 组件中使用：

javascript
console.log(process.env.VUE_APP_BASE_API) // 开发环境输出 /api，生产环境输出 http://www.xxx.com/api
console.log(process.env.VUE_APP_DEBUG) // 开发环境输出 true，生产环境输出 false
- 配置文件中使用（如 vue.config.js）：
javascript
module.exports = {
devServer: {
proxy: {
[process.env.VUE_APP_BASE_API]: { // 直接使用环境变量
target: 'http://localhost:8080',
changeOrigin: true
}
}
}
}

4. 自定义模式（可选）

若需要新增环境（如预发布环境），可创建 .env.staging 文件，然后在 package.json 中配置脚本：

json

{
"scripts": {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"build:staging": "vue-cli-service build --mode staging" // 预发布环境打包命令
}
}

执行 npm run build:staging 即可使用 .env.staging 中的环境变量。

五、静态资源的处理

Vue CLI 3.X 中静态资源主要存放于 public 目录和 src/assets 目录，两者处理方式不同，需注意区分。

1. 两个静态资源目录的区别

目录	处理方式	访问方式	适用场景
public	不经过 webpack 打包	通过绝对路径访问（如 /logo.png）	大文件、第三方库、index.html 引用的资源
src/assets	经过 webpack 打包（压缩、哈希）	通过相对路径或 import 访问	小图片、CSS、JS 等项目内资源

2. 具体使用示例

（1）src/assets 目录资源使用

- 图片资源（如 src/assets/img/logo.png ）：

vue

<img src="../assets/img/logo.png" alt="logo">

<script>
import logo from '@/assets/img/logo.png' // @ 等价于 src 目录
export default {
data() {
return { logo }
}
}
</script>
<template>
<img :src="logo" alt="logo">
</template>
- CSS 资源（如 src/assets/style/main.less ）：
javascript
// main.js 中全局引入
import '@/assets/style/main.less'

（2）public 目录资源使用

- 图片资源（如 public/favicon.ico ）：

vue

<img src="/favicon.ico" alt="favicon">
- 第三方库（如 public/js/jquery.min.js ）：
html

<script src="/js/jquery.min.js"></script>

3. 静态资源路径注意事项

- 打包后 public 目录下的资源会原样复制到 dist 目录，访问路径需配合 publicPath 配置。

- 若使用 src/assets 中的资源，webpack 会自动处理图片压缩、文件名哈希（避免缓存），推荐优先使用。

- 当资源体积超过 4KB 时，webpack 会将其转为 base64 编码（减少网络请求），可通过 vue.config.js 中的 chainWebpack 配置调整阈值。

4. 特殊场景：动态加载静态资源

若需要动态加载 src/assets 中的资源（如根据变量切换图片），需使用 require 语法：

vue
<template>
<img :src="getImageUrl('logo.png')" alt="动态图片">
</template>
<script>
export default {
methods: {
getImageUrl(name) {
// 动态加载 src/assets/img 目录下的图片
return require(`@/assets/img/${name}`)
}
}
}
</script>

六、Vue CLI 3.X 核心用法总结

1. 安装：需 Node.js 8.9+，全局执行 npm install -g @vue/cli ，通过 vue create 或 vue ui 创建项目；

2. 插件：用 vue add 安装官方/第三方插件， npm uninstall 卸载，支持命令行或图形化操作；

3. 配置：手动创建 vue.config.js ，可配置端口、代理、打包路径、CSS 预处理器等；

4. 环境变量：创建 .env.xxx 文件（变量名前缀 VUE_APP_ ），区分开发/生产等环境，通过 process.env 访问；

5. 静态资源： src/assets 经 webpack 打包， public 原样复制，分别通过相对/绝对路径访问。

VueCLI3.X安装与配置全攻略