【环境配置】使用 Vue CLI 构建 Vue 项目脚手架完整指南

Vue CLI 是 Vue.js 官方提供的标准化开发工具，它基于 Webpack 构建，集成了 Babel、ESLint 等现代化前端开发工具链，能够帮助开发者快速搭建一个开箱即用的 Vue 项目脚手架。尽管目前官方更推荐使用基于 Vite 的 create-vue 来创建新项目，但 Vue CLI 仍然是大量存量项目的基础，掌握其使用方法依然十分必要。

本文将从环境准备、工具安装、项目创建到目录结构解析，带你完整走一遍 Vue CLI 构建项目的全流程。

一、环境准备

在安装 Vue CLI 之前，首先需要确保本地环境中已安装 Node.js。

1.1 Node.js 版本要求

Vue CLI 4.x 要求 Node.js 8.9 或更高版本
Vue CLI 5.x 要求 Node.js 12 或更高版本

建议安装 Node.js 的 LTS（长期支持）版本以获得最佳的稳定性和兼容性。可通过以下命令检查当前 Node 版本：

bash 复制代码

node -v
npm -v

1.2 配置国内镜像源（可选但推荐）

由于 npm 官方源在国内访问速度较慢，建议配置淘宝镜像源以提升安装速度：

bash 复制代码

npm config set registry https://registry.npmmirror.com

配置完成后可通过以下命令验证：

bash 复制代码

npm config get registry

1.3 安装 cnpm 工具（可选）

cnpm 是淘宝 npm 镜像的官方命令行客户端，内置国内镜像源，无需额外修改 npm 全局配置即可高速下载依赖。如果你不想改动 npm 默认源，又想享受国内加速，可以单独安装 cnpm 工具。

通过 npm 并指定淘宝镜像源，全局安装 cnpm：

bash 复制代码

npm install -g cnpm --registry=https://registry.npmmirror.com

安装完成后，执行以下命令验证是否安装成功：

bash 复制代码

cnpm -v

输出版本号即表示安装成功。后续所有 npm install 类操作，都可以替换为 cnpm install，默认从国内镜像拉取包，速度与配置全局源一致。

二、安装 Vue CLI

Vue CLI 3.0 之后的包名由 vue-cli 变更为 @vue/cli，安装命令有所不同。

2.1 使用 npm 全局安装

bash 复制代码

npm install -g @vue/cli

若需要安装指定版本，可在包名后添加版本号：

bash 复制代码

npm install -g @vue/cli@5.0.8

2.2 使用 cnpm 全局安装

若已按上文步骤安装好 cnpm，可直接使用 cnpm 进行全局安装，无需额外配置源：

bash 复制代码

cnpm install -g @vue/cli

注意：如果之前安装过旧版 vue-cli（2.x），需要先卸载再安装新版本：

bash 复制代码

npm uninstall vue-cli -g

2.3 验证安装

安装完成后，执行以下命令验证是否安装成功并查看版本号：

bash 复制代码

vue --version
# 或简写
vue -V

正常情况下会输出版本号，例如 @vue/cli 5.0.8，表示安装成功。

三、使用 Vue CLI 创建项目

3.1 创建项目命令

在目标目录下打开终端，执行创建命令：

bash 复制代码

vue create my-vue-project

项目命名规范 ：项目名称不支持大写字母和驼峰命名，推荐使用小写字母加连字符的方式，如 my-project、hello-world。

3.2 交互式配置选择

执行创建命令后，会进入交互式配置界面，需要依次选择项目配置。

第一步：选择预设模式

html 复制代码

? Please pick a preset: (Use arrow keys)
  Default ([Vue 3] babel, eslint)
  Default ([Vue 2] babel, eslint)
> Manually select features

Default：默认预设，仅包含 Babel 和 ESLint，适合快速原型开发
Manually select features：手动选择功能，适合生产级项目定制

第二步：选择功能特性

按空格键勾选需要的功能，按回车确认：

html 复制代码

? Check the features needed for your project:
 (*) Babel
 ( ) TypeScript
 ( ) Progressive Web App (PWA) Support
 (*) Router
 (*) Vuex
 (*) CSS Pre-processors
 (*) Linter / Formatter
 ( ) Unit Testing
 ( ) E2E Testing

各功能说明：

功能	说明
Babel	ES6+ 语法转译，必选
TypeScript	支持 TypeScript 开发
PWA Support	渐进式 Web 应用支持
Router	vue-router 路由管理
Vuex	状态管理（Vue 3 也可后续替换为 Pinia）
CSS Pre-processors	CSS 预处理器（Sass/Less/Stylus）
Linter / Formatter	代码规范检查与格式化
Unit Testing	单元测试
E2E Testing	端到端测试

第三步：后续细化配置

根据所选功能，还会依次出现以下配置项：

选择 Vue 版本 ：2.x 或 3.x，新项目推荐选择 3.x
路由模式：是否使用 History 模式（需要后端配合）
CSS 预处理器：选择 Sass/SCSS、Less 或 Stylus
ESLint 配置：选择代码规范方案
lint 触发时机：保存时校验 / 提交时校验
配置文件存放方式：独立配置文件 / 全部放在 package.json
是否保存为预设：可将当前配置保存为预设，后续项目直接复用

3.3 启动开发服务器

项目创建完成后，进入项目目录并启动开发服务器：

bash 复制代码

cd my-vue-project
npm run serve

如果使用 cnpm，依赖安装阶段也可替换为 cnpm 命令：

bash 复制代码

cd my-vue-project
cnpm install
cnpm run serve

启动成功后，终端会输出访问地址：

html 复制代码

  App running at:
  - Local:   http://localhost:8080/
  - Network: http://192.168.1.100:8080/

在浏览器中访问 http://localhost:8080 即可看到项目首页。

3.4 常用命令速查

bash 复制代码

# 启动开发服务器
npm run serve

# 生产环境打包构建
npm run build

# 代码格式检查与修复
npm run lint

四、项目文件结构详解

项目创建完成后，根目录结构如下所示，下面逐一说明各文件和目录的作用。

html 复制代码

my-vue-project/
├── node_modules/       # 项目依赖包
├── public/             # 公共静态资源
│   ├── index.html      # HTML 入口模板
│   └── favicon.ico     # 网站图标
├── src/                # 源代码主目录
│   ├── assets/         # 静态资源（图片、样式等）
│   ├── components/     # 公共组件
│   ├── views/          # 页面级组件
│   ├── router/         # 路由配置
│   ├── store/          # Vuex 状态管理
│   ├── App.vue         # 根组件
│   └── main.js         # 项目入口文件
├── .gitignore          # Git 忽略配置
├── babel.config.js     # Babel 配置
├── package.json        # 项目依赖与脚本
├── vue.config.js       # Vue CLI 配置文件（可选，需手动创建）
└── README.md           # 项目说明文档

4.1 根目录文件说明

node_modules/ 存放所有 npm 安装的项目依赖包，由 npm install 自动生成，无需手动修改。该目录通常不提交到 Git 仓库。

public/ 存放不会被 Webpack 构建处理的静态资源，打包时会原样复制到 dist 目录中。适合存放 favicon.ico、robots.txt 以及第三方不支持模块化引入的库文件。

public/index.html 项目的 HTML 入口模板文件。Vue CLI 在构建时会将打包后的 JS、CSS 资源自动注入到该文件中。页面挂载点 <div id="app"></div> 就定义在这里。

package.json 项目的核心配置文件，包含项目名称、版本号、依赖包列表以及 npm 脚本命令等信息。

babel.config.js Babel 的配置文件，用于配置 ES6+ 语法转译规则、插件和预设。

.gitignore Git 版本控制的忽略文件配置，默认已忽略 node_modules、dist 等无需提交的目录。

vue.config.js Vue CLI 的可选配置文件，用于自定义 Webpack 配置、开发服务器端口、代理设置、打包路径等。该文件默认不存在，需要手动创建。

4.2 src 目录详解

src 是项目开发的核心目录，90% 以上的代码工作都在这里完成。

main.js 项目的入口文件，负责创建 Vue 实例、挂载根组件、注册插件等。

javascript 复制代码

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'

createApp(App).use(store).use(router).mount('#app')

App.vue 项目的根组件，所有页面组件都通过它进行渲染。通常包含顶部导航、侧边栏等全局布局，以及 <router-view> 路由出口。

assets/ 存放需要被 Webpack 处理的静态资源，如图片、字体、全局样式文件等。与 public 目录不同，这里的资源会被 Webpack 打包压缩，支持模块化引用。

components/ 存放可复用的公共组件，如按钮、表单、弹窗等通用 UI 组件。这些组件通常不包含业务逻辑，可在多个页面中复用。

views/ 存放页面级组件，对应路由中的每一个页面。通常按照业务模块划分子目录，如 views/home/、views/user/ 等。

router/ 路由配置目录，通常包含 index.js 文件，定义路由表、路由守卫等。

store/ Vuex 状态管理目录，存放全局状态、mutations、actions 等。如果使用 Pinia，则对应目录为 stores/。

4.3 扩展目录建议

随着项目复杂度提升，通常还会新增以下目录：

utils/：存放通用工具函数
api/：存放接口请求封装
directives/：自定义指令
composables/：Vue 3 组合式函数（Composition API 复用逻辑）
styles/：全局样式文件、变量、混合宏

五、vue.config.js 常用配置

在项目根目录创建 vue.config.js 文件，可以对 Vue CLI 进行自定义配置。以下是一些常用配置示例：

javascript 复制代码

module.exports = {
  // 部署应用包时的基本 URL
  publicPath: './',
  
  // 生产环境构建输出目录
  outputDir: 'dist',
  
  // 开发服务器配置
  devServer: {
    port: 8080,
    open: true,
    // 接口代理配置
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  },
  
  // 是否在生产环境生成 sourceMap
  productionSourceMap: false,
  
  // 关闭 eslint 保存检查（不推荐）
  lintOnSave: false
}

六、总结

Vue CLI 作为 Vue 生态的官方脚手架工具，极大地降低了前端工程化的入门门槛。通过本文的介绍，你应该能够独立完成从环境搭建、工具安装到项目创建的完整流程，并对生成的项目目录结构有清晰的认识。

国内开发环境下，无论是直接配置 npm 全局镜像源，还是使用 cnpm 工具，都能有效提升依赖安装速度，可根据团队习惯选择合适的方案。掌握项目目录中每个文件的作用，是后续进行业务开发、性能优化和问题排查的基础。建议在实际开发中遵循官方推荐的目录规范，保持项目结构的清晰与可维护性。