React+ts+vite脚手架搭建（五）【规范篇】

前言

上一篇我们介绍了如何在脚手架中配置mock：React+ts+vite脚手架搭建（四）【mock篇】

本篇我们将介绍一下脚手架的规范，包括两个：代码格式规范 、代码提交规范。

相信大家都了解统一代码格式规范的好处，好的代码规范是给未来维护者的礼物，那么开始

具体步骤

先从代码格式规范开始

代码格式规范

解释ESLint和Prettier区别

其实代码格式规范我们常用的就是ESLint和Prettier，相信很多人都对这两个有些许的混淆，这里我们先分别解释一下两者的作用和区别：

维度	ESLint	Prettier
核心目标	检查代码质量（错误、风险、最佳实践）	统一代码格式（美观、一致性）
关注范围	既包含代码风格，也包括逻辑正确性	只关注代码格式，不涉及逻辑
规则类型	部分规则可自动修复（如 --fix），部分需要手动修改（如未定义变量）	所有规则均可自动修复（直接重写格式）

简单来说：

• ESLint解决代码对不对（质量）；
• Prettier解决代码好不好看（格式）；

我们常常在具体的实践中两者都用，但是两者可能会存在冲突，例如 ESLint 有 quotes 规则（强制单引号），而 Prettier 也有同名配置，若规则不一致会导致格式化后 ESLint 报错。

我这里的解决方法是：

• 用 eslint-config-prettier 禁用 ESLint 中所有与 Prettier 冲突的 "格式类规则"（让 ESLint 专注于代码质量，不再管格式）；
• 用 eslint-plugin-prettier 将 Prettier 的格式规则 "注入" 到 ESLint 中，让 Prettier 的格式化结果作为 ESLint 的一条规则来检查（即格式不符合 Prettier 时，ESLint 会报错）。

简单来说，就是ESLint检查代码质量、逻辑正确性 的部分还是用自己的规范，但是检测代码风格 的部分全用Prettier。

安装依赖

这里要注意node的版本为20以上，否则下载依赖会报错

yarn add eslint prettier --save-dev
yarn add eslint-config-prettier eslint-plugin-prettier --save-dev

除了这四个依赖，我们还需要下载五个增强ESLint代码检查能力的插件或解析器

yarn add @typescript-eslint/eslint-plugin --save-dev
yarn add @typescript-eslint/parser --save-dev
yarn add eslint-plugin-react --save-dev
yarn add eslint-plugin-react-hooks --save-dev
yarn add eslint-plugin-react-refresh --save-dev

作用分别是：

依赖名称	类型	核心作用	主要应用场景
@typescript-eslint/parser	解析器	将TypeScript代码转换为ESLint可理解的AST，让ESLint支持TypeScript语法	TypeScript项目中使用ESLint的基础依赖
@typescript-eslint/eslint-plugin	插件	提供TypeScript专属的ESLint检查规则（如类型规范、类型安全等）	TypeScript项目的代码风格约束和潜在问题检查
eslint-plugin-react	插件	提供React特有的代码检查规则（如JSX语法、组件生命周期、props使用等）	React项目的代码规范性和最佳实践保障
eslint-plugin-react-hooks	插件	检查React Hooks的使用规范（如依赖数组完整性、禁止条件调用等）	使用React Hooks的项目，避免Hooks相关逻辑bug
eslint-plugin-react-refresh	插件	检测可能导致React Refresh（热更新）失效的代码写法	配置了React热更新的开发环境，确保热更新正常

配置规则文件

通过配置文件定义 ESLint 和 Prettier 的具体规则

配置 ESLint（eslint.config.js）

在项目根目录创建 eslint.config.js，定义检查规则

具体的配置解释可以参考注释

// ESLint 扁平配置文件 (ESLint 9.x 推荐格式)
import js from '@eslint/js';
import globals from 'globals';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import tseslint from 'typescript-eslint';
import prettierPlugin from 'eslint-plugin-prettier';
import prettierConfig from 'eslint-config-prettier';
import reactPlugin from 'eslint-plugin-react';
import tseslintParser from "@typescript-eslint/parser";

// 导出 ESLint 配置
export default [
  // 全局忽略规则：指定需要忽略的文件或目录
  { ignores: ['dist', 'node_modules', 'build'] },
  
  // 基础配置：适用于所有文件
  {
    languageOptions: {
      // 环境变量：同时支持浏览器和 Node.js 环境
      globals: {
        ...globals.browser,
        ...globals.node
      },
      
      // 解析器：使用 TypeScript 解析器
      parser: tseslintParser,
    }
  },
  
  // JavaScript 推荐规则
  js.configs.recommended,
  
  // TypeScript 推荐规则
  ...tseslint.configs.recommended,
  
  // 适配 prettier
  prettierConfig,
  
  // TypeScript 和 React 文件的特定配置
  {
    // 应用范围：仅对 TypeScript 和 TypeScript React 文件生效
    files: ['**/*.{ts,tsx}'],
    
    // 语言选项配置
    languageOptions: {
      ecmaVersion: 2020,
      sourceType: 'module',
      parser: tseslint.parser,
      globals: globals.browser
    },
    
    // 启用的插件 - 使用对象格式
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
      'prettier': prettierPlugin,
      'react': reactPlugin
    },
    
    // 自定义规则配置
    rules: {
      // React Hooks 规则
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'off',
      
      // React 热更新规则
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true }
      ],
      
      // TypeScript 规则
      '@typescript-eslint/no-empty-function': 'off',
      '@typescript-eslint/ban-ts-comment': 'off',
      '@typescript-eslint/no-var-requires': 'error',
      '@typescript-eslint/no-unused-vars': 'off',
      '@typescript-eslint/no-explicit-any': 'off',
      
      // Prettier 规则
      'prettier/prettier': 'error',
      
      // 其他规则
      'prefer-const': 'off'
    }
  },
  
  // JavaScript 文件的特定配置
  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 2020,
      sourceType: 'module'
    }
  }
];

集成到开发流程

添加 npm 脚本（package.json）

 "lint": "eslint .", // 检查所有文件的 ESLint 问题（包括格式）
 "lint:fix": "eslint . --fix" ,// 自动修复可修复的问题（包括 ESLint 错误和 Prettier 格式）

尝试分别运行一下两个命令

yarn lint

结果如下，会在控制台打印出来所有不符合的地方：

yarn lint:fix

结果如下，你可以一次性的修改所有不符合规范的地方：

代码提交规范

下载依赖

我们先下载两个依赖husky和lint-staged

yarn add husky -D
yarn add lint-staged -D

其中husky是 Git 提供的一种机制，允许在特定的 Git 操作（如 commit、push、merge 等）前后自动执行自定义脚本。例如：

• 在代码提交前（pre-commit 钩子）检查代码是否符合规范
• 在推送代码前（pre-push 钩子）执行单元测试
• 在提交信息写入前（commit-msg 钩子）校验提交信息格式

而lint-staged 是一个只针对 Git 暂存区（staged）文件运行代码检查 / 格式化工具的工具

初始化husky

npx husky init

会自动生成的 .husky 目录和指令：

配置pre-commit

npx lint-staged

配置package.json文件

......
"husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": [
      "eslint --fix", 
      "eslint"
    ]
  },
......

总结

到了这一步我们的代码格式规范和代码提交规范已经基本搭建完毕，希望能够帮助到大家