Vue 3 CLI TypeScript 项目搭建全攻略

一、前期准备

在搭建 Vue 3 CLI TypeScript 项目之前，我们需要做好一系列的准备工作。

首先，Node.js 是必不可少的运行环境。Vue 3 CLI 要求 Node.js 的版本至少为 8.9 以上。您可以从Node.js 官方网站下载最新的长期支持（LTS）版本。安装完成后，您可以在终端通过输入 node -v 命令来确认安装是否成功并查看所安装的版本。

其次，对于 Vue CLI 的安装和更新，如果您之前尚未安装 Vue CLI，或者您安装的是旧版本（1.x 或 2.x），则需要先进行卸载。卸载命令为 npm uninstall vue-cli -g 或 yarn global remove vue-cli 。然后，您可以通过以下命令安装最新版本的 Vue CLI：npm install -g @vue/cli 。安装完成后，您可以通过 vue -V 命令来查看安装的版本，确保安装成功且版本符合项目需求。

做好这些前期准备工作，将为我们后续顺利搭建 Vue 3 CLI TypeScript 项目奠定坚实的基础。

二、项目创建步骤

（一）默认创建方式

使用默认选项创建项目相对较为简单直接。在终端输入 vue create 项目名称 命令后，系统会为您自动选择一系列预设的配置。但需要注意的是，默认配置可能无法完全满足您的特定需求，如果您的项目有特殊的要求，比如需要特定的 CSS 预处理器、路由模式、状态管理等，默认配置可能就不太适用。

（二）手动选择特性创建

当您选择手动选择特性创建项目时，将面临一系列的配置选项。首先是基础选项，如 Babel 用于转换 ES6 语法，TypeScript 为项目提供类型支持。Router 用于管理路由，能让页面之间的跳转更加清晰和可控。Vuex 用于状态管理，便于集中管理和共享应用中的状态数据。

对于 CSS Pre-processors ，您可以根据团队习惯和项目需求选择 Less、Sass 等预处理器。Linter/Formatter 用于代码规范和格式检查，保证代码的质量和一致性。

在选择是否使用 class-style component syntax 时，如果您更习惯使用类的方式来组织组件，建议选择开启。对于 Use Babel alongside TypeScript ，通常建议选择开启，以便更好地处理类型转换。

在路由模式选择上，如果您希望 URL 看起来更简洁美观，可选择 Use history mode for router ，但要注意在生产环境中需进行相应的服务器配置。

对于 CSS 预处理器的选择，应根据项目的样式需求和团队成员的熟悉程度来决定。而在选择代码检查工具和代码格式化时机时，需要考虑团队的开发习惯和项目的规范要求。

总之，手动选择特性创建项目时，需要综合考虑项目的具体需求和团队的技术偏好，做出最适合的配置选择。

三、项目配置与优化

（一）常用配置项详解

路由模式：常见的路由模式有 hash 模式和 history 模式。hash 模式通过 # 后面的部分来标识不同的页面，兼容性较好；history 模式则使 URL 看起来更加美观和直观，但需要服务器进行相应配置以避免 404 错误。

CSS 预处理器：Less 预处理器具有动态特性，允许在 CSS 中进行变量定义、函数编写和嵌套规则。而 Sass 则具有更强大的功能和丰富的语法。

代码检查工具：ESLint 可以通过配置规则来检查代码中的语法错误、潜在问题和风格不一致。例如，可以设置禁止使用未声明的变量、限制每行代码的长度等规则。

（二）代码规范与格式化

配置 ESLint ：首先需要安装相关依赖，如 npm install eslint --save-dev 。然后创建 .eslintrc.js 文件来配置规则，如设置代码缩进、禁止使用特定的语法等。

Prettier 用于统一代码格式，安装后创建 .prettierrc 文件来配置格式选项，如缩进方式、行长度等。还可以在 package.json 中添加脚本，实现一次性格式化项目中的所有文件。

为了避免 ESLint 和 Prettier 的冲突，还需要安装一些插件并在 .eslintrc.js 中进行相应配置。

（三）UI 框架集成与优化

以 Element UI 为例，按需加载可以通过以下步骤实现：首先安装 Element UI ，然后在项目的入口文件（如 main.js ）中按需引入所需的组件。还可以通过配置 babel-plugin-component 来进一步优化加载性能。

在配置优化方面，可以根据项目的具体需求定制主题，修改组件的默认样式，以达到与项目风格的完美融合。

四、项目搭建注意事项

（一）常见错误与解决

在 Vue 3 CLI TypeScript 项目搭建过程中，可能会遇到以下常见错误及解决方法：

• 安装 CLI 插件出错：可能会出现 Installing CLI plugins. This might take a while... 这样的报错。解决方法包括降低 npm 版本、清空 npm 缓存、卸载相关包后重新安装等。

• 组件 props 报错对象可能为空：在组件的根节点增加 v-if 不为空判断来解决。

• api.now is not a function 错误：通常和 vue devtools 有关系，重新禁用启用，或者重新安装来解决。

• 组件名称不符合规范：要求组件名称以驼峰格式命名。但实际开发时，一般页面组件我们以 index 命名，组件才以驼峰格式命名。在 .eslintrc.cjs 文件中，增加 vue/multi-word-component-name 配置来解决。

（二）兼容性处理

为了处理不同浏览器和环境的兼容性问题，我们可以采取以下方案：

• 使用 rem 代替 px ：引入 lib-flexible 和 px2rem 自动转换 px 为 rem ，解决响应式问题。在 vue.config.js 中新增相应配置，设置合适的换算基数。

• 进行 CSS reset ：使用 normalize.css 或者自行编写一套重置方案，重置所有浏览器默认样式。

• 使用 Polyfill ：通过 JavaScript 模拟实现浏览器不支持的 API 或者标准 API，例如使用 pollyfill.js 或者 core-js 等库。

• 进行 Feature detection ：通过检测浏览器特性来判断是否支持某个功能，使用 Modernizr 或者自行编写脚本来实现。

（三）版本控制与代码提交

利用 git 钩子可以实现代码校验和规范提交。首先，在安装 @vue/cli-service 之后，会安装 yorkie ，它能让我们在 package.json 的 gitHooks 字段中方便地指定 Git hook。例如：

{"gitHooks":{"pre-commit":"lint-staged"},"lint-staged":{"*.{js,vue}":["vue-cli-service lint","git add"]}}

注意，lint-staged 需要安装，否则会报找不到命令。在 commit 时有警告提示某些任务使用了 git add 命令，建议将其删除，因为 lint-staged 会将格式化后的代码自动添加到当前 commit 中。

如果使用 husky ，可以自动安装配置 lint-staged 和 husky ，修改 package.json 中的相关配置。在代码提交前，还可以进行分支合并前的代码审查，使用流行的代码审查工具如 GitHub 的 Code Review 等，提高代码质量。规范 commit 的信息，使用简洁明了的格式，方便跟踪和管理代码。