K8凯发(中国)天生赢家·一触即发

从 0 开始手把手带你搭建一套规范的 Vue3x 项目工程环境
栏目:k8凯发集团 发布时间:2025-09-16
 Vue3 跟 Vite 正式版发布有很长一段时间了,生态圈也渐渐丰富起来,作者已在多个项目中使用,总结一下:就是快!也不用担心稳定性问题,开发体验真不是一般好!还没尝试的同学可以从本文开始学习,从 0 开始手把手带你搭建一套规范的 Vite + Vue3 + TypeScript 前端工程化项目环境。  你还可以通过附加的命令行选项直接指定项目名和模板,本项目要构建 Vite + Vue3 +

  Vue3 跟 Vite 正式版发布有很长一段时间了,生态圈也渐渐丰富起来,作者已在多个项目中使用,总结一下:就是快!也不用担心稳定性问题,开发体验真不是一般好!还没尝试的同学可以从本文开始学习,从 0 开始手把手带你搭建一套规范的 Vite + Vue3 + TypeScript 前端工程化项目环境。

  你还可以通过附加的命令行选项直接指定项目名和模板,本项目要构建 Vite + Vue3 + TypeScript 项目,则运行:

  本项目先做一些简单配置,例如:设置@指向src目录、 服务启动端口、打包路径、代理等。

  根据本项目路由配置的实际情况,你需要在src下创建views目录,用来存储页面组件。

  为了使项目的目录结构合理且规范,我们在src下创建utils目录来存储我们常用的工具函数。

  本项目使用 CSS 预编译器 Stylus,直接安装为开发依赖即可。Vite 内部已帮我们集成了相关的 loader,不需要额外配置。同理,你也可以使用 Sass 或 Less 等。

  下面我们来打磨这个项目,增加代码规范约束、提交规范约束、单元测试、自动部署等,让其更完善、更健壮。

  随着前端应用逐渐变得大型化和复杂化,在同一个项目中有多个人员参与时,每个人的前端能力程度不等,他们往往会用不同的编码风格和习惯在项目中写代码,长此下去,势必会让项目的健壮性越来越差。解决这些问题,理论上讲,口头约定和代码审查都可以,但是这种方式无法实时反馈,而且沟通成本过高,不够灵活,更关键的是无法把控。不以规矩,不能成方圆,我们不得不在项目使用一些工具来约束代码规范。

  EditorConfig 有助于为不同 IDE 编辑器上处理同一项目的多个开发人员维护一致的编码风格。

  Prettier 配置好以后,在使用 VSCode 或 WebStorm 等编辑器的格式化功能时,编辑器就会按照 Prettier 配置文件的规则来进行格式化,避免了因为大家编辑器配置不一样而导致格式化后的代码风格不统一的问题。

  ESLint是一款用于查找并报告代码中问题的工具,并且支持部分问题自动修复。其核心是通过对代码解析得到的 AST(Abstract Syntax Tree 抽象语法树)进行模式匹配,来分析代码达到检查代码质量和风格问题的能力。

  正如前面我们提到的因团队成员之间编程能力和编码习惯不同所造成的代码质量问题,我们使用 ESLint 来解决,一边写代码一边查找问题,如果发现错误,就给出规则提示,并且自动修复,长期下去,可以促使团队成员往同一种编码风格靠拢。

  这三份风格指南都是由众多大佬根据多年开发经验编写,足够优秀,全球很多大小公司都在使用。我们选用GitHub 上 star 最多的 Airbnb,免去繁琐的配置 ESLint 规则时间,然后让团队成员去学习 Airbnb JavaScript 风格指南即可。

  此时,我们在 ESLint 配置了 Airbnb JavaScript 规则,在编码时,所有不符合 Airbnb 风格的代码,编辑器都会给出提示,并且可以自动修复。

  这里作者不建议大家去自由配置 ESLint 规则,相信我,这三份 JavaScript 代码风格指南值得我们反复学习,掌握后,编程能力能上一大台阶。

  根据上面的选择,ESLint 会自动去查找缺失的依赖,我们这里选择Yes,使用 NPM 下载安装这些依赖包。

  配置好以后,我们在 VSCode 或 WebStorm 等编辑器中开启 ESLin,写代码时,ESLint 就会按照我们配置的规则来进行实时代码检查,发现问题会给出对应错误提示和修复方案。

  虽然,现在编辑器已经给出错误提示和修复方案,但需要我们一个一个去点击修复,还是挺麻烦的。很简单,我们只需设置编辑器保存文件时自动执行eslint --fix命令进行代码风格修复。

  通常大家会在项目中根据实际情况添加一些额外的 ESLint 和 Prettier 配置规则,难免会存在规则冲突情况。

  k8凯发官网

  本项目中的 ESLint 配置中使用了 Airbnb JavaScript 风格指南校验,其规则之一是代码结束后面要加分号,而我们在 Prettier 配置文件中加了代码结束后面不加分号的配置项,这样就有冲突了,会出现用 Prettier 格式化后的代码,ESLint 检测到格式有问题的,从而抛出错误提示。

  这样,我们在执行eslint --fix命令时,ESLint 就会按照 Prettier 的配置规则来格式化代码,轻松解决二者冲突问题。

  我们在项目中已集成 ESLint 和 Prettier,在编码时,这些工具可以对我们写的代码进行实时校验,在一定程度上能有效规范我们写的代码,但团队可能会有些人觉得这些条条框框的限制很麻烦,选择视“提示”而不见,依旧按自己的一套风格来写代码,或者干脆禁用掉这些工具,开发完成就直接把代码提交到了仓库,日积月累,ESLint 也就形同虚设。

  所以,我们还需要做一些限制,让没通过 ESLint 检测和修复的代码禁止提交,从而保证仓库代码都是符合规范的。

  为了解决这个问题,我们需要用到 Git Hook,在本地执行git commit的时候,就对所提交的代码进行 ESLint 检测和修复(即执行eslint --fix),如果这些代码没通过 ESLint 规则校验,则禁止提交。

  特别注意:本项目使用 husky 6.x 版本,6.x 版本配置方式跟之前的版本有较大差异。目前网上大部分有关 husky 的教程都是 6 以前的版本 ,跟本文教程不太一样,当发现配置方法不一致时,一切以husky 官网为准。

  但是又存在一个问题:有时候我们明明只改动了一两个文件,却要对所有的文件执行eslint --fix。假如这是一个历史项目,我们在中途配置了 ESLint 规则,那么在提交代码时,也会对其他未修改的“历史”文件都进行检查,可能会造成大量文件出现 ESLint 错误,显然不是我们想要的结果。

  我们要做到只用 ESLint 修复自己此次写的代码,而不去影响其他的代码。所以我们还需借助一个神奇的工具lint-staged。

  lint-staged 这个工具一般结合 husky 来使用,它可以让 husky 的hook触发的命令只作用于git add那些文件(即 git 暂存区的文件),而不会影响到其他文件。

  无论写代码还是做其他事情,都应该用长远的眼光来看,刚开始使用 ESint 的时候可能会有很多问题,改起来也很费时费力,只要坚持下去,代码质量和开发效率都会得到提升,前期的付出都是值得的。

  这些工具并不是必须的,没有它们你同样可以可以完成功能开发,但是利用好这些工具,你可以写出更高质量的代码。特别是一些刚刚接触的人,可能会觉得麻烦而放弃使用这些工具,失去了一次提升编程能力的好机会。

  本项目完整的代码托管在GitHub 仓库,有需要的同学可以去下载下来,参考学习。

  前面我们已经统一代码规范,并且在提交代码时进行强约束来保证仓库代码质量。多人协作的项目中,在提交代码这个环节,也存在一种情况:不能保证每个人对提交信息的准确描述,因此会出现提交信息紊乱、风格不一致的情况。

  如果git commit的描述信息精准,在后期维护和 Bug 处理时会变得有据可查,项目开发周期内还可以根据规范的提交信息快速生成开发日志,从而方便我们追踪项目和把控进度。

  这里,我们使用社区最流行、最知名、最受认可的 Angular 团队提交规范。

  如上图,可以看出这些提交信息都是有固定格式的,下面我们来学习 Angular 规范的 commit message 格式。

  scope 用于指定本次 commit 影响的范围。scope 依据项目而定,例如在业务项目中可以依据菜单或者功能模块划分,如果是组件库开发,则可以依据组件划分。(scope 可省略)

  subject 是本次 commit 的简洁描述,长度约定在 50 个字符以内,通常遵循以下几个规范:

  body 是对本次 commit 的详细描述,可以分成多行。(body 可省略)

  跟 subject 类似,用动词开头,body 应该说明修改的原因和更改前后的行为对比。

  如果本次提交的代码是突破性的变更或关闭缺陷,则 Footer 必需,否则可以省略。

  上面介绍了 Angular 规范提交的格式,初次接触的同学咋一看可能会觉得复杂,其实不然,如果让大家在git commit的时候严格按照上面的格式来写,肯定是有压力的,首先得记住不同的类型到底是用来定义什么,subject 怎么写,body 怎么写,footer 要不要写等等问题,懒才是程序员第一生产力,为此我们使用 Commitizen 工具来帮助我们自动生成 commit message 格式,从而实现规范提交。

  以前我们提交代码都是git commit -m xxx,现在改为git cz,然后按照终端操作提示,逐步填入信息,就能自动生成规范的 commit message。

  从上面的截图可以看到,git cz终端操作提示都是英文的,如果想改成中文的或者自定义这些配置选项,我们使用cz-customizable适配器。

  运行如下命令使用 cz-customizable 初始化项目,注意之前已经初始化过一次,这次再初始化,需要加--force覆盖。

  在项目根目录下创建.cz-config.js文件,然后按照官方提供的示例来配置。

  建议大家结合项目实际情况来自定义配置提交规则,例如很多时候我们不需要写长描述,公司内部的代码仓库也不需要管理 issue,那么可以把询问 body 和 footer 的步骤跳过(在.cz-config.js中修改成skipQuestions: [body, footer])。

  在“代码规范”章节,我们已经讲到过,尽管制定了规范,但在多人协作的项目中,总有些人依旧我行我素,因此提交代码这个环节,我们也增加一个限制:只让符合 Angular 规范的 commit message 通过,我们借助 @commitlint/config-conventional 和 @commitlint/cli 来实现。

  因为已在项目中集成 commitizen,建议大家用git cz来代替git commit提交代码,可以保证提交信息规范。

  本项目完整的代码托管在GitHub 仓库,同学可以去下载下来,参考学习。

  单元测试是项目开发中一个非常重要的环节,完整的测试能为代码和业务提供质量保证,减少 Bug 的出现。

  我们使用 Vue 官方提供的vue-test-utils和社区流行的测试工具jest来进行 Vue 组件的单元测试。

  因为我们在项目中集成了 ESLint,如上图很明显是没通过 ESLint 规则检验。因此,我们还需要在 ESLint 中增加eslint-plugin-jest插件来解除对 jest 的校验。

  现在,我们的单元测试代码就不会有错误提示信息了 ؏؏☝ᖗ 乛 ◡ 乛 ᖘ☝؏؏

  你可以在jest.config.js配置文件中,自由配置单元测试文件的目录。

  当单元测试没有全部通过时,我们需要根据报错信息去优化对应组件的代码,进一步提高项目健壮性。但是写单元测试是件比较痛苦的事,我个人觉得也没必要全部组件都写单元测试,根据项目实际情况有针对性去写就行了。

  前面,我们使用 husky 在 Git 的pre-commit和commit-msg阶段分别约束代码风格规范和提交信息规范。这一步,我们在pre-push阶段进行单元测试,只有单元测试全部通过才让代码push到远端仓库,否则终止push。

  现在,我们在git push时就能先进行单元测试了,只有单元测试全部通过,才能成功push。

  本项目完整的代码托管在GitHub 仓库,同学可以去下载下来,参考学习。

  到了这一步,我们已经在项目中集成代码规范约束、提交信息规范约束,单元测试约束,从而保证我们远端仓库(如 GitHub、GitLab、Gitee 仓库等)的代码都是高质量的。

  本项目是要搭建一套规范的前端工程化环境,为此我们使用 CI(Continuous Integration 持续集成)来完成项目最后的部署工作。

  GitHub Actions 是 GitHub 的持续集成服务,持续集成由很多操作组成,比如抓取代码、运行测试、登录远程服务器、发布到第三方服务等等,GitHub 把这些操作称为 actions。

  gh-pages分支,是 GitHub Pages 服务的固定分支,可以通过 HTTP 的方式访问到这个分支的静态文件资源。

  注意:新生成的 Token 只会显示一次,保存起来,后面要用到。如有遗失,重新生成即可。

  当有新提交的代码push到 GitHub 仓库时,就会触发 GitHub Actions,在 GitHub 服务器上执行 Action 配置文件里面的命令,例如:安装依赖、项目打包等,然后将打包好的静态文件部署到 GitHub Pages 上,最后,我们就能通过域名访问了。

  使用自动部署,我们只需专注于项目开发阶段,任何重复且枯燥的行为都交由程序去完成,懒才是程序员第一生产力。

  事实上,自动部署只是 GitHub Actions 功能的冰山一角,GitHub Actions 能做的事还很多很多,大家感兴趣的话自行查阅。

  本文从技术选项到架构搭建、从代码规范约束到提交信息规范约束,从单元测试到到自动部署,一步一步带领大家如何从一个最简单的前端项目骨架到规范的前端工程化环境,基本涵盖前端项目开发的整个流程,特别适合刚接触前端工程化的同学学习。