使用 Vue CLI 创建 Vue.js 项目的详细指南

前言

在现代前端开发的世界里，Vue.js 作为一款渐进式 JavaScript 框架，以其简单易用和灵活性赢得了广泛的欢迎。它允许开发者从构建单个视图的组件到创建复杂的单页应用程序（SPA）。为了加速开发过程并提供最佳实践的脚手架工具，Vue CLI 应运而生。Vue CLI 是一个官方提供的命令行工具，用于快速搭建 Vue.js 项目的基础结构。它不仅简化了项目的初始化流程，还集成了现代前端开发所需的各种功能，如热重载、ESLint 集成、路由配置等。

本指南将详细介绍如何使用 Vue CLI 创建一个新的 Vue.js 项目，帮助你掌握从安装 Vue CLI 到启动你的第一个 Vue.js 应用程序的所有步骤。无论你是刚刚接触 Vue.js 的新手，还是希望提高工作效率的老手，这份指南都将为你提供有价值的见解和实用的操作技巧。

一、Vue CLI 简介

Vue CLI（Command Line Interface）是 Vue.js 官方提供的命令行工具，旨在加速基于 Vue.js 的 Web 应用程序的开发过程。它提供了一套完整的工具链，用于创建、构建和维护现代前端项目。通过 Vue CLI，开发者可以快速搭建一个具有丰富功能的项目模板，并且可以根据需要轻松添加或移除特性。

Vue CLI 的主要特点

1. 脚手架生成器：
   • Vue CLI 提供了一个强大的脚手架生成器，可以帮助开发者在几秒钟内设置好一个全新的 Vue.js 项目。这个生成器支持多种预设配置，允许开发者选择最适合他们需求的项目结构和技术栈。
2. 插件系统：
   • Vue CLI 拥有一个丰富的插件生态系统，这些插件可以扩展项目的功能，例如添加 TypeScript 支持、PWA 功能、单元测试框架等。这使得开发者可以根据项目的需求灵活地定制开发环境。
3. 图形用户界面 (GUI)：
   • Vue CLI 不仅限于命令行操作，还提供了一个图形用户界面（Vue CLI GUI），让用户可以通过可视化的方式管理项目和插件，这对于不熟悉命令行操作的用户来说非常友好。
4. 现代 JavaScript 工具链集成：
   • Vue CLI 内置了对 Babel、ESLint、PostCSS 等现代 JavaScript 工具的支持，确保开发者能够使用最新的语言特性和最佳实践进行编码。
5. 优化的构建配置：
   • Vue CLI 自动生成的 webpack 配置经过高度优化，以实现高效的开发体验和生产构建。它包括代码分割、懒加载、Tree Shaking 等功能，有助于减少打包体积并提高应用性能。
6. 跨平台兼容性：
   • Vue CLI 是完全跨平台的，可以在 Windows、macOS 和 Linux 上运行，保证了不同操作系统间的无缝协作。
7. 社区支持与文档：
   • Vue CLI 背后有活跃的开源社区支持，官方文档详尽，遇到问题时很容易找到帮助和支持。

Vue CLI 带来的便利

• 提升开发效率：通过自动化处理重复的任务，如文件生成、依赖安装等，使开发者能够更专注于业务逻辑的实现。
• 降低入门门槛：对于初学者而言，Vue CLI 提供了清晰易懂的命令和选项，简化了项目初始化的过程。
• 保持技术更新：随着 Vue CLI 的持续迭代，它会引入新的特性和改进，确保项目始终处于技术前沿。
• 增强团队协作：统一的项目结构和开发规范有助于团队成员之间更好地理解和协作，尤其是在大型项目或多人协作环境中。
• 促进代码质量：结合 Linter/Formatter 插件，可以自动检查和格式化代码，提高代码质量和一致性。

二、环境准备

在开始使用 Vue CLI 创建项目之前，确保你的计算机上已经正确安装了 Node.js 和 npm（Node Package Manager）。这是因为 Vue CLI 依赖于 Node.js 运行时和 npm 来管理项目依赖。以下是详细的步骤来帮助你完成环境的准备工作：

1. 安装 Node.js 和 npm

• 下载与安装
  • 访问 Node.js 官方网站。
  • 根据你的操作系统选择 LTS (长期支持) 版本进行下载。LTS 版本通常更稳定，更适合生产环境。
  • 按照安装向导提示完成安装。请注意，在 Windows 上，安装程序会自动将 Node.js 和 npm 添加到系统的 PATH 环境变量中；而在 macOS 或 Linux 上，你可能需要手动确认这一点。
• 验证安装
  • 打开命令行工具（Windows 用户可以使用 PowerShell 或者 CMD，macOS 和 Linux 用户可以使用终端）。
  • 输入以下命令以检查 Node.js 是否安装成功，并查看其版本号：

    node -v
    

  如果两个命令都能返回相应的版本号，则说明安装成功。

2. 更新 npm (可选但推荐)

有时，随着 Node.js 的更新，npm 可能不是最新的版本。为了确保我们拥有所有最新功能和安全修复，建议更新 npm 至最新版本：

npm install -g npm

3. 配置 npm (根据需要)

• 设置镜像源：如果你位于中国或网络条件不佳，可能会遇到从默认 npm 仓库下载包速度慢的问题。此时，你可以考虑切换到国内镜像源，如淘宝 NPM 镜像：

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

• 清理缓存：如果遇到任何问题，尝试清理 npm 缓存可能有助于解决问题：

  npm cache clean --force
  

4. 安装 Vue CLI

现在你的环境中已经有了 Node.js 和 npm，接下来就可以安装 Vue CLI 了：

npm install -g @vue/cli

这将全局安装 Vue CLI 工具，使得 vue 命令可以在系统中的任何地方运行。

5. 验证 Vue CLI 安装

安装完成后，可以通过下面的命令来验证 Vue CLI 是否安装成功：

vue --version

或者简写为：

vue -V

如果一切顺利，你应该能看到 Vue CLI 的版本信息，这意味着你已经成功设置了用于创建 Vue.js 项目的开发环境。

6. （可选）配置 Vue CLI

• 图形用户界面 (GUI)：Vue CLI 提供了一个图形界面，可以让你无需记住复杂的命令行选项。要启动 GUI，请运行：

  vue ui
  

  然后按照屏幕上的指示操作即可。

三、创建新项目

在你已经正确设置了开发环境（包括安装了 Node.js 和 npm，以及全局安装了 Vue CLI）之后，接下来就可以使用 Vue CLI 来创建一个新项目。以下是详细的创建步骤：

1. 打开命令行工具

首先，打开你的命令行工具（如 Windows 的 PowerShell 或 CMD、macOS 或 Linux 的终端）。这将是我们与 Vue CLI 交互的主要界面。

2. 创建新项目

在命令行中，导航到你想要创建项目的目录，然后运行以下命令来启动项目创建过程：

vue create my-project

这里的 my-project 是你项目的名称，你可以根据需要替换为其他名称。执行该命令后，Vue CLI 将引导你完成一系列设置选项。

3. 选择预设或手动配置

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

在使用 Vue CLI 创建新项目时，CLI 会提供几个预设选项供你选择。这些预设是为了加快项目的创建过程而设计的模板，它们已经预先配置好了常用的功能组合。这里有三个主要选项：

• Default ([Vue 3] babel, eslint)：这是为 Vue 3 版本准备的默认预设，它包含了 Babel（用于编译现代 JavaScript 代码）和 ESLint（用于代码风格检查和错误预防）。如果你想要快速开始一个基于最新版 Vue 的项目，并且希望包含这两个工具，那么这是一个很好的起点。
• Default ([Vue 2] babel, eslint)：这个预设与上面类似，但它是为 Vue 2 设计的。如果你需要兼容 Vue 2 或者你的项目依赖于尚未迁移到 Vue 3 的某些库或插件，你可以选择这个选项。
• Manually select features：如果你有特定的需求或者想要更精细地控制项目的配置，可以选择手动选择特性。这将允许你从多个选项中挑选适合你项目的配置，例如是否包含 TypeScript、Router、Vuex 等等。

使用键盘上的上下箭头键来导航到你想要选择的预设，然后按下 Enter 键确认选择。我这里选择 “Manually select features”，接下来我将详细介绍如何进行手动配置。

? Check the features needed for your project: (Press <space> to select, <a> to toggle all, <i> to invert selection, and
<enter> to proceed)
>(*) Babel
 ( ) TypeScript
 ( ) Progressive Web App (PWA) Support
 ( ) Router
 ( ) Vuex
 ( ) CSS Pre-processors
 (*) Linter / Formatter
 ( ) Unit Testing
 ( ) E2E Testing

• Babel：Babel 是一个 JavaScript 编译器，它允许你使用最新的 JavaScript 语法编写代码，然后将其转换为向后兼容的版本，以便在旧版浏览器中运行。
• TypeScript：TypeScript 是一种静态类型的编程语言，它是 JavaScript 的超集。它可以提高代码质量，尤其是在大型项目中。如果你喜欢静态类型检查，可以考虑选中它。
• Progressive Web App (PWA) Support：PWA 支持可以让你的应用像原生应用一样工作，具有离线支持、推送通知等功能。如果你的应用需要这些功能，应该保留这个选项。
• Router：路由模块用于实现单页面应用程序（SPA）中的导航。如果你计划创建一个多页面布局的应用程序，那么这将是必要的。
• Vuex：Vuex 是 Vue.js 应用的状态管理模式。如果你需要管理全局状态或者组件之间的共享数据，建议保留这个选项。
• CSS Pre-processors：CSS 预处理器如 Sass 或 Less 可以使样式表更易于维护和扩展。如果你熟悉并希望使用预处理器，可以保留此选项。
• Linter / Formatter：代码格式化工具和 Linter 可以帮助保持代码风格的一致性，并自动修复一些常见的错误。这对团队协作非常有用。
• Unit Testing：单元测试是针对代码库中的小部分（通常是函数或方法）进行的测试。如果你重视测试驱动开发（TDD），可以考虑添加这一项。
• E2E Testing：端到端测试（E2E）模拟真实用户的行为来测试整个应用程序的工作流程。对于确保应用程序各部分正确集成非常重要。

? Choose a version of Vue.js that you want to start the project with (Use arrow keys)
> 3.x
  2.x

• 3.x：这是最新的 Vue 版本，包含了多项改进和新功能，如 Composition API、更好的 TypeScript 支持等。如果你从头开始一个新项目，并且不需要考虑与旧版插件或库的兼容性问题，推荐使用 Vue 3。
• 2.x：如果你需要确保与某些特定的 Vue 2 插件或库的兼容性，或者你的团队尚未准备好迁移到 Vue 3，可以选择 Vue 2。不过请注意，Vue 2 的长期支持 (LTS) 已经结束，因此建议尽可能地向 Vue 3 迁移。

? Use history mode for router? (Requires proper server setup for index fallback in production) (Y/n)

是否使用 history 路由模式，这种模式兼容不好，所以这里输入 n 不使用。

一旦选择了 Vue 版本，CLI 将根据你的选择继续配置项目。对于每个选中的特性，CLI 会进一步询问具体的配置选项。

? Pick a CSS pre-processor (PostCSS, Autoprefixer and CSS Modules are supported by default): (Use arrow keys)
  Sass/SCSS (with dart-sass)
> Less
  Stylus

选择你熟悉的 CSS 预处理器

? Pick a linter / formatter config:
  ESLint with error prevention only
  ESLint + Airbnb config
> ESLint + Standard config
  ESLint + Prettier

? Pick additional lint features: (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to
proceed)
 (*) Lint on save
>(*) Lint and fix on commit

选择在什么时机下触发代码格式校验：

• Lint on save：每当保存文件的时候
• Lint and fix on commit：每当执行 git commit 提交的时候

建议两个都选上，更严谨

? Where do you prefer placing config for Babel, ESLint, etc.? (Use arrow keys)
> In dedicated config files
  In package.json

Babel、ESLint 等工具会有一些额外的配置文件，这里的意思是问你将这些工具相关的配置文件写到哪里：

• In dedicated config files：分别保存到单独的配置文件
• In package.json：保存到 package.json 文件中

这里建议选择第 1 个，保存到单独的配置文件，这样方便我们做自定义配置。

? Save this as a preset for future projects? (y/N)

这里里是问你是否需要将刚才选择的一系列配置保存起来，然后它可以帮你记住上面的一系列选择，以便下次直接重用。

• 根据自己需要输入 y 或者 n，我这里输入 n 不需要。

🗃  Initializing git repository...
⚙️  Installing CLI plugins. This might take a while...


added 830 packages in 40s

104 packages are looking for funding
  run `npm fund` for details
🚀  Invoking generators...
📦  Installing additional dependencies...

\

向导配置结束，开始装包。
安装包的时间可能较长，请耐心等待…

⚓  Running completion hooks...

📄  Generating README.md...

🎉  Successfully created project my-project.
👉  Get started with the following commands:

 $ cd my-project
 $ npm run serve

安装结束，命令提示你项目创建成功，按照命令行的提示在终端中分别输入：

# 进入你的项目目录
cd my-project

# 启动开发服务
npm run serve

 INFO  Starting development server...
 
 DONE  Compiled successfully in 4255ms                                                                          15:58:09

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

  Note that the development build is not optimized.
  To create a production build, run npm run build.

启动成功，命令行中输出项目的 http 访问地址。
打开浏览器，输入其中任何一个地址进行访问。

如果能看到该页面，恭喜你，项目创建成功了。

四、项目结构解析

my-project
├── node_modules              第三方包存储目录
├── public                    任何放置在 public 文件夹的静态资源都会被简单的复制，而不经过 webpack。
│   ├── favicon.ico           浏览器收藏夹图标
│   └── index.html            单页面 HTML 文件
├── src
│   ├── assets                公共资源目录，放图片等资源
│   ├── components            公共组件目录
│   ├── router                Vue Router 路由模块
│   ├── store                 Vue 容器模块
│   ├── views                 视图组件存储目录，所有的路由页面都存储到这里
│   ├── App.vue               根组件，最终被替换渲染到 index.html 页面中 #app 入口节点
│   └── main.js               整个项目的启动入口模块
├── .browserslistrc           指定了项目的目标浏览器的范围。这个值会被 @babel/preset-env 和 Autoprefixer 用来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀
├── .editorconfig             EditorConfig 帮助开发人员定义和维护跨编辑器（或IDE）的统一的代码风格，详情参考这里：https://editorconfig.org/。
├── .eslintrc.js              ESLint 的配置文件
├── .gitignore                Git 的忽略配置文件，告诉Git项目中要忽略的文件或文件夹
├── babel.config.js           Babel 的配置文件
├── jsconfig.js               Javascript配置文件，用于 Visual Studio Code 等编辑器 
├── lint-staged.config.js     配置 lint-staged 工具，用于在提交前自动运行代码检查和修复
├── package-lock.json         记录安装时的包的版本号，以保证自己或其他人在 npm install 时大家的依赖能保证一致
├── package.json              包说明文件，记录了项目中使用到的第三方包依赖信息等内容
├── README.md                 说明文档
└── vue.config.js             Vue CLI 的配置文件，用于自定义构建和开发环境的配置

结语

通过本指南，我们已经了解了使用 Vue CLI 创建 Vue.js 项目的整个流程，从环境准备到最终的应用程序运行。Vue CLI 提供的强大功能和灵活配置，使得我们可以专注于编写业务逻辑，而不必过多担心项目的构建细节。随着不断深入学习和实践，你将会发现 Vue CLI 及其丰富的插件生态能够极大地提升开发效率，并为你的项目带来更多的可能性。

希望这份指南能成为你在 Vue.js 开发旅程中的得力助手，鼓励你去探索更多关于 Vue.js 和 Vue CLI 的知识。无论是继续深入了解框架内部的工作原理，还是开始构建你自己的应用，我们都期待看到你所创造的精彩作品。祝愿你在使用 Vue CLI 进行开发的过程中，能够轻松应对挑战，享受编程的乐趣。