【前端工程化最新版】（一）项目搭建篇-vite5&vue3.5、prettier、eslint9、Commitlint、lint-staged、husky

赵小川
690 阅读7分钟

🧑‍💻 写在开头

本系列使用 前端最新技术，搭建一个完整的项目基建以及一些核心功能点的实现。 主要技术栈涉及 vue-3.5.x、eslint-9.x、vite-5.x、 prettier、 commitlint、lint-staged、typescript、vue-router pina、element-plus, unocss, 以及vite-5.x 中的一些打包配置，插件配置，别名配置，与构建配置等。注意（ vite 需要 Node.js 版本 18+ 或 20+。 eslint9.x对于Node.js < v18.18, v19 are no longer supported``所以要考虑好是否要升级node 版本，最好是21.1.x 以上的版本 。 然而，有些模板需要依赖更高的 Node 版本才能正常运行，当你的包管理器发出警告时，请注意升级你的 Node 版本。）

🧀 你能学到什么

  1. 一个最新的、标准的项目初始化、代码规范、提交规范的配置流程
  2. eslint、prettier的配置 & 自动保存修复
  3. git 提交规范，以及git 相关配置

🍎 使用vite5项目初始化（vue+ts）

vite 官方文档

pnpm create vite vue3-admin --template vue-ts

image.png

🍎 代码规范

🔧 1. 代码检测工具 eslint

1.1 🌰 安装 和初始化 eslint

npx eslint --init

最后会生成一个eslint.config.js 文件

image.png

是的 这是eslint 9 相对于 之前版本的一个升级，将之前的 .eslintrc 都变为了 在 eslint.config.js 对eslint 进行配置。

那接下来就详细介绍一下eslint.config.js的一些默认配置

import globals from 'globals';
import pluginJs from '@eslint/js'; // 检验js规范的 (推荐)
import tseslint from 'typescript-eslint'; // 推荐的ts规范
import pluginVue from 'eslint-plugin-vue'; //推荐的vue的规范

export default [
  // 1. 检测文件的格式
  { files: ['**/*.{js,mjs,cjs,ts,vue}'] },
  // 2. 定义不同环境的全局变量
  { languageOptions: { globals: { ...globals.browser, ...globals.node } } },
  // 3. js 推荐 规则
  pluginJs.configs.recommended,
  // 4. ts 推荐 规则
  ...tseslint.configs.recommended,
  // 5. vue 推荐 规则
  ...pluginVue.configs['flat/essential'],
  // 6. 检测 vue 中的 ts 代码采用 tsparser
  {
    files: ['**/*.vue'],
    languageOptions: { parserOptions: { parser: tseslint.parser } },
  },
];

🌰 1.2 添加ignores 选项(忽略掉一些文件的eslint检测)

eslint-8 是配置.eslintignore,而现在是直接在eslint.config.js 进行配置

  • 配置项方式
export default [
  // 7. ignores 配置
  {
    ignores: [
      'node_modules/*',
      'dist/*',
      '*.css',
      '*.jpg',
      '*.jpeg',
      '*.png',
      '*.gif',
      '*.d.ts',
    ],
  },
];
  • 文件引入的方式

import { includeIgnoreFile } from "@eslint/compat";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url); // 使用 fileURLToPath 将当前模块的 import.meta.url 转换为文件路径
const __dirname = path.dirname(__filename); // 使用 path.dirname 获取当前文件所在的目录路径。
const gitignorePath = path.resolve(__dirname, ".gitignore"); // 解析 .gitignore 文件路径

export default [
    includeIgnoreFile(gitignorePath),
    {
        // your overrides
    }
];

🌰 1.3 vscode 安装 eslint 插件

image.png

  • 在 vscode 中安装 eslint 插件：一般 eslint 只做检测代码规范

  • 同时可以将 eslint 插件添加到 vscode 建议中

image.png

image.png

这样下次别人在打开项目时，如果没有安装工作区的插件，vscode 会提示安装项目所需要的插件

image.png

image.png

这样 新接手的项目人员，插件就可以保持一致

🌰 1.4 自定义校验规则

// 8. 自定义规则,根据需要增加  eslint 主要是校验代码规范  prettier格式化代码的
  {
    rules: {
      'no-console': 'error', // 参照下方实例图
      'vue/multi-word-component-names': 'off',
    },
  },

image.png

// 8. 自定义规则,根据需要增加  eslint 主要是校验代码规范  prettier  格式化代码的
  {
    rules: {
      'no-console': 'warn', // 参照下方实例图
      'vue/multi-word-component-names': 'off',
    },
  },

image.png

🌰 1.5 package.json 中添加eslint 脚本

{  
"lint": "eslint", // 校验  
"lint:fix": "eslint --fix --quiet" // 校验时忽略警告，并修复  
}

🔧 2. 代码风格工具 Prettier 配置

🌰 2.1 插件安装

pnpm add prettier eslint-plugin-prettier eslint-config-prettier -D
  • prettier: 美化代码
  • eslint-plugin-prettier: 在eslint 中集成prettier
  • eslint-config-prettier: 如果prettier 和eslint 有冲突，eslint-plugin-prettier 会借助eslint-config-prettier 对冲突进行合并，最终以 prettier的规则为准
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'; // 覆盖掉eslint的规范


export default [
   // 9. 将其放在最后一项，覆盖掉eslint的格式化规范
  eslintPluginPrettierRecommended,
  ]

🌰 2.2 在 vscode 中安装 Prettier 插件

image.png

  • Prettier 只是用来格式化代码。这里需要新建 prettier.config.js 配置代码⻛格
export default {  
    singleQuote: false, // 使用单引号  
    semi: false, // 末尾添加分号  
    tabWidth: 2,  
    trailingComma: "none",  
    useTabs: false,  
    endOfLine: "auto",  
};

安装 Prettier 插件，设置 Default Formatter 选择 Prettier - Code formatter；并配置 Format On Save 为启用，保存时自将动格式化

image.png

设置保存时，自动格式化

image.png

.prettierignore

新建 .prettierignore 文件

# Ignore all JavaScript files in the /dist folder
dist/**/*.js

# Ignore all files in the /build folder
build/

# Ignore specific configuration files
*.config.js

# Ignore JSON files
*.json

# Ignore node_modules (though it’s ignored by default)
node_modules/

🌰 2.3 编辑器统一配置： EditorConfig for VS Code

安装 EditorConfig for VS Code 插件，新
建.editorconfig 文件 （编辑器设置保持一致）

image.png

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf

至此我们的 项目初始化、eslint、prettier 都 搭建完成，下面开始git 规范 搭建

🍎 git规范

🔧 4. git 提交规范 husky

实际项目中，代码格式化一般是配合 git hook 使用；实现提交代码前，

  • 第一：先进行校验 比如 存在报错的，我们不允许提交

  • 第二：做代码格式化

image.png

  • 🌰 4.1 git仓库初始化
git init
  • 🌰 4.2 安装husky包
pnpm add husky lint-staged -D
  • 🌰 4.3 安装 和 初始化 husky
npx husky init
  • 🌰 4.4 在 package.json 中配置lint-staged相关信息
"lint-staged": {  
"src/**/*.{js,jsx,cjs,ts,vue}": [  
"npm run lint:fix"  
],  
"src/**/*.{html,json,css,scss}": [  
"npx prettier --write"  
]  
}

image.png

image.png

当修改完❌后，再次提交

image.png

🔧 5. commit 规范

  • 🌰 5.1 插件安装
pnpm add @commitlint/cli @commitlint/config-conventional -D
  • 🌰 5.2 增添 commitlint.config.cjs 配置文件
module.exports = {
  extends: ["@commitlint/config-conventional"],
};
  • 🌰 5.3 添加commit 钩子 新建 commit-msg
npx --no-install commitlint --edit $1

image.png

image.png ❌ 说我们必须添加一个类型，他的类型有以下几种

  • 类型描述
    build编译相关的修改，例如发布版本、对项目构建或者依赖的改动
    chore其他修改, 比如改变构建流程、或者增加依赖库、工具等
    ci持续集成修改
    docs文档修改
    feat新特性、新功能
    fix修改bug
    perf优化相关，比如提升性能、体验
    refactor代码重构
    revert回滚到上一个版本
    style代码格式修改, 注意不是 css 修改
    test测试用例修改

image.png

至此项目初始化，以及 vue3.5、prettier、eslint9、Commitlint、lint-staged、husky 等项目基本配置完毕，下面想解答一些我在开发过程中遇到的一些问题

🙋 问题答疑

1. npx 和 npm 的区别，npx eslint --init 执行了什么，可以换成npm 吗

可以换成 npm， 只不是npx 执行了安装和初始化

npx eslint --init 相当于

  1. pnpm add eslint -D

  2. npm eslint --init

2. 配置文件规范权重

settings.json > 规范设置 > vscode 工作区基本配置

  • 如果在 .vscode/settings.json 设置了 格式化的规范，那么其他都失效，这个是权重最大的。如果想项目里规范化万无一失，一定要配settings.json

image.png

{
  // =======================下面是配置prettier格式化的setting===================
  // 指定哪些文件不参与搜索
  "search.exclude": {
    "**/node_modules": true,
    "dist": true,
    "build": true,
    "package-lock.json": true
  },

  "[javascript]": {
    "editor.defaultFormatter": "vscode.typescript-language-features"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[scss]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "editor.tabSize": 2,
  // 保存自动格式化
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}
  • 规范设置

image.png

一定要选择 prettier-code fomatter

image.png

  • vscode 工作区基本配置

image.png

2. 遇到prettier不生效，selint 不生效，冲突问题解决

原因及解决

  • 电脑太卡，导致eslint 检测半天加载不出来， 此时可以执行page.json 里面的lint 命令，查看项目不规范的代码。 或者重启编辑器
  • 检查eslint 和 prettier 的vscode 插件是否安装
  • 检查eslint 和 prettier 的npm 包管理是否安装
  • 检查项目当前设置的默认Formatter 方式是什么，具体参照上面 2.2
  • 实在不行，都没有生效，在.vscode下添加 settings.json，强制项目的格式化，具体参照 问题答疑 2中配置

3. git配置别名

具体可参考官网 ： git-scm.com/book/zh/v2/…

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status

🍊 写在最后

如果您看到这里了，并且觉得这篇文章对您有所帮助，希望您能够点赞👍和收藏⭐支持一下作者🙇🙇🙇，感谢🍺🍺！如果文中有任何不准确之处，也欢迎您指正，共同进步。感谢您的阅读，期待您的点赞👍和收藏⭐！

本次项目仓库地址： github.com/github-lear…

基建分支：main , 后续每开发一个新的模块会在单独分支，方便阅读

后续会做成cli， 新项目直接cli 全套就有了

下一篇

  • 后台项目周边技术栈接入以及vite相关配置
avatar
文章
阅读
粉丝