react react18+vite+typeScript+eslint+prettier+husky+lint-staged+commitlint 快速搭建项目环境

最新推荐文章于 2025-04-19 14:31:57 发布

小白小白从不日白

最新推荐文章于 2025-04-19 14:31:57 发布

阅读量1.8k

点赞数 4

CC 4.0 BY-SA版权

分类专栏： react 文章标签： react.js typescript 前端

本文链接：https://blog.csdn.net/weixin_43285360/article/details/142333437

react 专栏收录该内容

4 篇文章

订阅专栏

技术栈

react18
react-router6
antd5
zustand4
vite45
axios
fakerjs 模拟数据
dayjs
lodash
typescript
echarts
commitlint、prettier、eslint
husky、lint-staged
自定义commitlint、cz-cli
自定义eslint、prettier

代码规范技术栈

代码格式规范和语法检测

vscode：统一前端编辑器。
editorconfig: 统一团队 vscode 编辑器默认配置。
prettier: 保存文件自动格式化代码。
eslint: 检测代码语法规范和错误。
lint-staged: 只检测暂存区文件代码，优化 eslint 检测速度。

代码 git 提交规范

husky:可以监听githooks执行，在对应 hook 执行阶段做一些处理的操作。
pre-commit：githooks 之一，在 commit 提交前使用 tsc 和 eslint 对语法进行检测。
commit-msg：githooks 之一，在 commit 提交前对 commit 备注信息进行检测。
commitlint：在 githooks 的 pre-commit 阶段对 commit 备注信息进行检测。
commitizen：git 的规范化提交工具，辅助填写 commit 信息。

本项目大致目录结构

├─ public                     # 静态资源
│   ├─ favicon.ico            # favicon图标
├─ src                        # 项目源代码
│   ├─ components             # 全局公用组件
│   ├─ layout                 # 布局组件
│   ├─ config                 # 全局配置
│   │   └─ router.tsx         # 路由配置
│   ├─ services               # api接口
│   ├─ stores                 # 全局 store管理
│   ├─ utils                  # 全局公用方法
│   ├─ pages                  # pages 所有页面
│   ├─ App.tsx                # 入口页面
│   ├─ global.d.ts            # 全局声明文件
│   ├─ index.css              # 全局样式文件
│   └─index.tsx               # 源码入口
└── .commitlintrc.js          # 自定义commitlint
└── .cz-config.js             # 自定义commitlint
└── .eslintignore             # eslint忽略文件
└── .eslintrc.js              # eslint配置
└── .prettierrc.js            # prettier配置
└── vite.config.js            # vite打包配置
└── index.html                # html模板
└── package.json              # package.json

组件库

这里主要利用 antDesign 进行开发

官网地址：

https://procomponents.ant.design/

使用 react 脚手架创建项目

创建项目使用vite官网搭建第一个 vite 项目，因为要创建的是react+ts项目，执行命令

创建项目

首先确保已经安装了 nodejs
其次 npm 版本要大于 5.2
然后通过 npm 安装 npm i -g create-react-app
create-react-app --version 检测安装的版本
create-react-app 项目名称安装react项目；需要注意的是在创建react项目给项目命名的时候不允许有大写字母
或者直接通过以下命令：npx create-react-app react-basic(项目名称)，创建react项目
在本项目中，主要用的是 pnpm ，这里可以通过 npm 去安装 pnpm
项目默认是运行在http://localhost:3000 地址，启动成功后在浏览器打开。
启动项目：yarn start or npm start or pnpm start

editorconfig 统一编辑器配置

由于每个人的vsocde编辑器默认配置可能不一样，比如有的默认缩进是4个空格，有的是2个空格，如果自己编辑器和项目代码缩进不一样，会给开发和项目代码规范带来一定影响，所以需要在项目中为编辑器配置下格式。

安装 vscode 插件 EditorConfig

打开vsocde插件商店，搜索EditorConfig for VS Code，然后进行安装。

添加.editorconfig 配置文件

安装插件后，在根目录新增 .editorconfig配置文件:

root = true # 控制配置文件 .editorconfig 是否生效的字段

[**] # 匹配全部文件
indent_style = space # 缩进风格，可选space｜tab
indent_size = 4 # 缩进的空格数
charset = utf-8 # 设置字符集
trim_trailing_whitespace = true # 删除一行中的前后空格
insert_final_newline = true # 设为true表示使文件以一个空白行结尾
end_of_line = lf

[**.md] # 匹配md文件
trim_trailing_whitespace = false

上面的配置可以规范本项目中文件的缩进风格，和缩进空格数等，会覆盖vscode的配置，来达到不同编辑器中代码默认行为一致的作用

prettier 自动格式化代码

每个人写代码的风格习惯不一样，比如代码换行，结尾是否带分号，单双引号，缩进等，而且不能只靠口头规范来约束，项目紧急的时候可能会不太注意代码格式，这时候需要有工具来帮我们自动格式化代码，而prettier就是帮我们做这件事的

安装 vscode 插件 Prettier

打开vsocde插件商店，搜索Prettier - Code formatter，然后进行安装

添加.prettierrc.js 配置文件

安装插件后，在根目录新增 .prettierrc.js配置文件，配置内容如下：

module.exports = {
  printWidth: 120, // 一行的字符数，如果超过会进行换行
  tabWidth: 4, // 一个tab代表几个空格数，默认就是4
  useTabs: false, // 是否启用tab取代空格符缩进，.editorconfig设置空格缩进，所以设置为false
  semi: false, // 行尾是否使用分号，默认为true
  singleQuote: true, // 字符串是否使用单引号
  trailingComma: 'none', // 对象或数组末尾是否添加逗号 none| es5| all
  jsxSingleQuote: true, // 在jsx里是否使用单引号，你看着办
  bracketSpacing: true, // 对象大括号直接是否有空格，默认为true，效果：{ foo: bar }
  arrowParens: 'avoid' // 箭头函数如果只有一个参数则省略括号
}

添加.vscode/settings.json

配置前两步后，虽然已经配置prettier格式化规则，但还需要让vscode来支持保存后触发格式化

在项目根目录新建 .vscode文件夹，内部新建settings.json文件配置文件，内容如下：

{
  "search.exclude": {
    "/node_modules": true,
    "dist": true,
    "pnpm-lock.sh": true
  },
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "vscode.json-language-features"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[less]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[scss]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "liveServer.settings.port": 5502
}

先配置了忽略哪些文件不进行格式化，又添加了保存代码后触发格式化代码配置，以及各类型文件格式化使用的格式。

这一步配置完成后，修改项目代码，把格式打乱，点击保存时就会看到编辑器自动把代码格式规范化了。

项目目录结构说明

README.md：说明文档
package.json：对整个应用程序的描述，包括：应用名称、版本号、一些依赖包、以及项目的启动、打包等
public

- favicon.ico：应用程序顶部的icon图标
- index.html：相当于html模板文件，react最终会将模板挂载到html中的div元素上即应用程序的入口文件
- logo192.png：被在mainfest.json中使用
- logo512.png：被在mainfest.json中使用
- mainfest.json：和 web app 配置相关
- robots.txt：指定搜索引擎可以或者无法爬取哪些文件

- assets：存放一些静态资源，比如css、图片等
- components：存放项目中的一些自定义组件
- App.css：App组件相关的样式
- App.js：项目的根组件，相当于vue中的app.vue
- App.test.js：App组件的测试代码文件
- Index.css：全局样式文件
- index.js：项目的入口文件，相当于vue中的main.js
- logo.svg：启动项目所看到的图标
- reportWebVitals.js：
- setupTests.js：测试初始化文件

npm run start：启动项目，开服
npm run build：项目打包生产包
npm run eject：项目中的一些配置被隐藏起来了，通过这个命令可以将配置文件反编译到项目中，从而获得配置的权利，这个操作是不可逆的，一旦编译出来就无法编译回去，一般来说不会执行这个命令，我们会通过其他方式去修改配置。
说明：

- src 目录是我们写代码进行项目开发的目录
- 查看 package.json 两个核心库：react、react-dom（脚手架已经帮我们安装好，我们直接用即可）

相关插件安装和说明

faker.js

faker.js 数据模拟，类似于 mock，这里需要注意的是，如果我们直接通过 npm install fakerjs -D 则会报错：

- WARN Moving @testing-library/jest-dom that was installed by a different package manager to "node_modules/.ignored" WARN Moving @testing-library/react that was installed by a different package manager to "node_modules/.ignored" WARN Moving @testing-library/user-event that was installed by a different package manager to "node_modules/.ignored" WARN Moving react that was installed by a different package manager to "node_modules/.ignored" WARN Moving react-dom that was installed by a different package manager to "node_modules/.ignored" WARN 2 other warnings ERR_PNPM_NO_VERSIONS No versions available for fakerjs. The package may be unpublished.

其大致意思就是：是因为 fakerjs 这个包在 npm 上不存在或者已经被删除。事实上，faker.js 的原作者在 2021 年删除了这个包，因此我们会遇到这个错误。

解决的办法就是：安装 @faker-js/faker，通过 pnpm install @faker-js/faker -D 这样就能够成功安装并使用这个新的 faker 包了。

npm 地址：https://www.npmjs.com/package/@faker-js/faker

zustand

pnpm install zustand

一个小巧但强大的状态管理库，适用于 React 应用。

主要特点

简单易用：Zustand 提供了一个简洁的 API，使得状态管理变得非常简单和直观。你只需要几行代码就可以创建和使用状态。
性能高效：Zustand 采用了最小的 re-render 策略，只会在状态实际变化时触发组件重新渲染，避免了不必要的性能开销。
无依赖：Zustand 设计为无依赖的库，可以与任何 React 项目无缝集成，无需额外安装其他依赖。
TypeScript 支持：Zustand 提供了良好的 TypeScript 支持，使得开发更加顺畅和类型安全。
Server-Side Rendering (SSR)：Zustand 支持服务端渲染，适用于需要在服务端预渲染的 React 应用。
Server-Side Rendering (SSR)：Zustand 支持服务端渲染，适用于需要在服务端预渲染的 React 应用。

在 React18 中的作用

React18 带来了并发模式等新特性，这对状态管理库提出了更高的要求。Zustand 的简洁和高效使它非常适合在 React18 中使用：

并发特性兼容：React18 引入了并发模式，Zustand 设计为响应式的状态管理库，可以很好地兼容 React18 的并发特性，确保应用的状态管理在并发模式下仍然稳定和高效。
简化状态管理：在复杂的 React 应用中，使用 Zustand 可以大大简化状态管理逻辑，避免了 Redux 等库的繁琐配置和样板代码，使开发更加专注于业务逻辑。
轻量级替代：相比于 Redux、MobX 等更重的状态管理库，Zustand 是一个轻量级的替代方案，适合小到中型应用，甚至可以在大型应用中与其他状态管理库共同使用，负责管理局部状态

axios

网络请求工具

pnpm install axios

dayjs

pnpm install dayjs

轻量的处理时间和日期的 JavaScript 库，和 Moment.js 的 API 设计保持完全一样

中文文档地址：Day.js · 中文文档 - 2kB 大小的 JavaScript 时间日期库

lodash

pnpm install lodash

中文文档地址：Lodash 简介 | Lodash中文文档 | Lodash中文网

是一个一致性、模块化、高性能的 JavaScript 实用工具库

antd

pnpm install antd --save
pnpm install @ant-design/icons --save
pnpm install  @ant-design/pro-components
pnpm install @ant-design/plots

@ant-design/plots

Ant Design 生态系统中的一个数据可视化库，它基于 G2 (一个强大的数据可视化引擎) 构建。这个库旨在帮助开发者快速构建高质量的数据可视化图表，如柱状图、折线图、饼图等

功能和优势：

多种图表类型：支持常见的图表类型，包括柱状图、折线图、饼图、面积图、散点图、雷达图等。
易于使用：提供了简单的 API 接口，方便开发者快速上手，轻松创建复杂的图表。
高度可定制化：提供了丰富的配置选项，允许开发者根据需求进行定制。
响应式设计：默认支持响应式设计，可以在不同尺寸的屏幕上自适应显示。
与 React 结合良好：可以很好地与 React 结合，作为组件使用，方便在 React 项目中集成数据可视化功能。

@ant-design/pro-components

`@ant-design/pro-components` 是 Ant Design Pro 组件库的一部分，旨在提供一组高质量的 React 组件，用于构建复杂的企业级后台管理系统。这个库包括了常用的布局组件、表单组件、表格组件、图表组件等。

功能和优势：

Pro 级别组件：提供了很多高级组件，如 ProTable、ProForm、ProLayout 等，专为企业级应用设计。
提高开发效率：这些组件预设了很多默认配置，可以大大减少开发者的工作量，加快开发速度。
统一的设计规范：所有组件都遵循 Ant Design 的设计规范，确保界面的一致性和美观性。
灵活性和可扩展性：尽管有很多默认配置，这些组件仍然保持了高度的灵活性，允许开发者根据具体需求进行定制和扩展。
与 Ant Design 生态系统无缝集成：可以与 Ant Design 的其他组件和库无缝集成，构建复杂的应用更加简单。

rc-resize-observer

pnpm install rc-resize-observer

一个轻量级的 React 组件库，主要用于监听元素大小变化（Resize）。它基于 ResizeObserver API 实现，提供了一种简单而高效的方式来监控 DOM 元素的尺寸变化，并在变化时触发回调函数

主要作用：

监听元素尺寸变化：能够检测到元素宽度和高度的任何变化，包括窗口大小的变化、元素内容变化导致的尺寸变化等。
自动处理：当元素尺寸发生变化时，会自动触发回调函数，使开发者可以在回调函数中执行相应的逻辑处理。

常见用途：

响应式布局：在响应式设计中，监听元素尺寸变化后动态调整布局和样式。
动态内容调整：在内容动态变化时（例如文本内容增多或减少），自动调整元素大小或重新渲染相关组件。
自适应组件：创建自适应组件，能够根据容器尺寸变化自动调整内部元素的布局和样式。

react-router-dom

pnpm install react-router-dom

React 应用中最流行的路由库之一，它提供了一组组件和钩子，用于在单页应用（SPA）中实现路由和导航功能。这个库的主要作用和用途包括：

主要作用：

客户端路由：管理客户端的路由，使应用可以在不同 URL 之间切换而无需刷新整个页面。
路由组件：提供一组 React 组件，如 <BrowserRouter>, <Route>, <Switch>, <Link> 等，用于定义路由、导航链接和路由匹配逻辑。
动态路由：支持基于 URL 参数的动态路由，允许路由参数化并在组件中访问这些参数。
嵌套路由：支持嵌套路由，使应用可以在父路由内定义子路由，从而创建复杂的路由结构。
重定向和导航：提供重定向功能以及编程式导航，使开发者可以在代码中进行页面跳转和重定向。

主要用途：

单页应用（SPA）：在单页应用中实现多页面导航，使应用在用户切换页面时不刷新整个页面，而是动态加载内容。
路由管理：为应用提供路由管理功能，使开发者可以轻松定义和管理应用的不同视图和页面。
URL 参数：通过路由参数传递数据，使应用可以根据 URL 参数显示不同内容或执行不同逻辑。
导航链接：使用 <Link> 组件创建导航链接，使用户可以点击链接在不同页面之间切换。

该插件可以像vue中使用路由的那种方式去进行使用，以导入的形式

vite

pnpm install vite -D

构建打包插件，与webpack类似。

主要特点和作用：

快速冷启动：

- Vite 采用原生 ES 模块来处理开发环境下的模块导入，这意味着它可以在浏览器中直接使用 JavaScript 文件，无需对所有依赖进行预打包。这大大加快了项目的启动速度，特别是对于大型项目。

即时热更新 (HMR)：

- Vite 提供快速、精确的模块热替换 (HMR)，使开发者能够在不刷新整个页面的情况下看到代码更改的效果。这极大地提升了开发体验和效率。

优化的生产构建：

- Vite 内置了 Rollup 作为生产构建工具，支持开箱即用的代码拆分和高效的编译优化，生成的构建产物体积小、性能优。

现代化的开发特性：

- Vite 支持最新的 JavaScript 和 CSS 特性，并通过插件体系可以轻松扩展，满足不同框架和库的需求，如 React、Vue、Svelte 等。

typeScript 相关插件

pnpm install @types/jest @types/node @types/react @types/react-dom typescript

pnpm install @typescript-eslint/eslint-plugin @typescript-eslint/parser -D

@types/jest

这是 Jest 的类型定义文件。Jest 是一个常用的 JavaScript 测试框架，@types/jest 提供了 Jest API 的 TypeScript 类型定义，使你可以在 TypeScript 项目中使用 Jest 进行单元测试并享受类型检查和自动补全功能。

@types/node

这是 Node.js 的类型定义文件。Node.js 是一个 JavaScript 运行时，用于构建服务器端和命令行工具。@types/node 提供了 Node.js API 的 TypeScript 类型定义，使你可以在 TypeScript 项目中使用 Node.js 的内置模块（如 fs, http 等）并获得类型检查和自动补全功能。

@types/react

这是 React 的类型定义文件。React 是一个用于构建用户界面的 JavaScript 库，@types/react 提供了 React 核心库的 TypeScript 类型定义，使你可以在 TypeScript 项目中使用 React 进行组件开发并享受类型检查和自动补全功能。

@types/react-dom

这是 ReactDOM 的类型定义文件。ReactDOM 是 React 的一个包，用于在浏览器环境中渲染 React 组件。@types/react-dom 提供了 ReactDOM API 的 TypeScript 类型定义，使你可以在 TypeScript 项目中使用 ReactDOM 进行渲染并获得类型检查和自动补全功能。

typescript

这是 TypeScript 编译器本身。TypeScript 是 JavaScript 的超集，添加了静态类型和其他特性。安装 typescript 包括 tsc（TypeScript 编译器），用于将 TypeScript 代码编译成 JavaScript 代码。

vite-tsconfig-paths

用于解析 TypeScript 配置文件中的路径别名，使得在 Vite 项目中可以使用 TypeScript 的路径别名功能。安装该插件后，可以使 Vite 项目识别和解析 tsconfig.json 文件中配置的路径别名，从而简化模块的引入路径。

@typescript-eslint/eslint-plugin

这是一个 ESLint 插件，专为 TypeScript 提供的 linting 规则。
它包含了一系列针对 TypeScript 代码的 linting 规则，用于提高代码质量，确保一致的代码风格，并避免常见的错误。
配合 @typescript-eslint/parser 使用，可以在 ESLint 中解析和检查 TypeScript 代码。

@typescript-eslint/parser

这是一个 ESLint 解析器，用于解析 TypeScript 代码。
它将 TypeScript 代码解析为 ESLint 能够理解的抽象语法树 (AST)，从而使 ESLint 能够检查和 lint TypeScript 代码。
必须与 @typescript-eslint/eslint-plugin 一起使用，以支持 ESLint 对 TypeScript 代码的检查。

SASS

pnpm install sass -D

css 预处理插件

@vitejs/plugin-react

pnpm install @vitejs/plugin-react -D

这是一个 Vite 插件，专门用于支持 React 项目的开发。
它提供了 React 快速刷新 (Fast Refresh) 功能，使得在开发过程中，React 组件的状态能够保持不变，同时进行热更新，提升开发体验。
它还优化了 React 项目的构建和性能，使得开发和构建过程更加高效。

commitLint + prettier + eslint + husky + lintStaged 配置

pnpm install commitizen commitlint commitlint-config-cz cz-customizable eslint eslint-config-prettier eslint-plugin-prettier eslint-plugin-react husky lint-staged prettier -D

配置 ESLint

安装插件，打开vsocde插件商店，搜索ESLint，然后进行安装。

ESLint 是一个用来识别 ECMAScript 并且按照规则给出报告的代码检测工具，使用它可以避免低级错误和统一代码的风格。它拥有以下功能：

- 查出 JavaScript 代码语法问题。
- 根据配置的规则，标记不符合规范的代码。
- 自动修复一些结构、风格问题。

防止代码很难维护，可以帮我们检查有没有死循环，有没有定义但未使用的变量等等。
ESLint官方文档：ESLint - Pluggable JavaScript linter - ESLint中文
生成配置文件

ESLint配置文件名称可以为：.eslintrc.js、.eslint.config.js （根据个人习惯选择即可）
这里是我常用的配置规则，更多配置规则请查阅ESLint中文。单独的语法配置需要在rules中编写，全部配置请参考：List of available rules - ESLint中文

安装插件 pnpm install eslint -D，安装eslint后，执行 pnpm init @eslint/config命令，选择自己需要的配置

这里我们选择了

使用eslint检测并问题
项目使用的模块规范是es module
使用的框架是react
使用了typescript
代码选择运行在浏览器端
eslint配置文件使用js格式
是否现在安装相关依赖，选择是
使用pnpm包管理器安装依赖

在项目根目录下分别新建以下文件（也可以直接在项目根目录下新建以下文件）

.eslintrc.js

module.exports = {
    env: {
        browser: true, // 代码将在浏览器环境中运行，因此可使用浏览器的全局变量（如 window、document）
        es2021: true, // 允许使用 ECMAScript 2021（ES12）中的语言特性
        node: true, // 代码也可以在 Node.js 环境中运行
    },
    extends: [
        "eslint:recommended", //  继承 ESLint 的推荐规则集，包含了通用的最佳实践和常见错误检查
        "plugin:react/recommended", // 继承 eslint-plugin-react 插件的推荐规则，专门为 React 开发提供支持
        "plugin:@typescript-eslint/recommended", // 继承 @typescript-eslint 插件的推荐规则，专门为 TypeScript 提供支持
        "prettier", // 使用 Prettier 的规则来关闭所有可能与 Prettier 冲突的 ESLint 规则，确保代码格式一致
    ],
    overrides: [],
    parser: "@typescript-eslint/parser", // 使用 @typescript-eslint/parser 解析器，允许 ESLint 解析 TypeScript 代码
    parserOptions: {
        ecmaVersion: "latest", // 使用最新的 ECMAScript 标准语法
        sourceType: "module", // 指定代码是使用 ES 模块（import/export）而不是 CommonJS（require/module.exports）
    },
    // react: 使用 eslint-plugin-react 插件，提供 React 相关的 lint 规则。
    // @typescript-eslint: 使用 @typescript-eslint 插件，提供 TypeScript 相关的 lint 规则
    plugins: ["react", "@typescript-eslint"],
    rules: {
        "@typescript-eslint/no-unused-vars": [2], //禁止出现未使用的变量
        "no-var": 2, // 禁止使用 var 声明变量，错误级别为 2（error），鼓励使用 let 和 const
        "arrow-spacing": [2, { before: true, after: true }], // 强制箭头函数的箭头前后有空格，错误级别为 2（error）
        "@typescript-eslint/no-non-null-assertion": "off", // 关闭 TypeScript 的非空断言规则，允许使用非空断言操作符（!）
    },
};

.eslintignore

.eslintrc.js
node_modules
dist
.DS_Store
*.local

解决当前项目 eslint 语法错误(有可能会出现)

此时eslint基础配置就已经配置好了，此时要解决出现的几个小问题：

看App.tsx页面会发现jsx部分有红色报红，提示 'React' must be in scope when using JSX

这是因为React18版本中使用jsx语法不需要再引入React了，根据eslint-react-plugin中的说明，如果使用了react17版本以上，不需要在使用jsx页面引入React时，在eslint配置文件 .eslint.js的extends字段添加插件plugin:react/jsx-runtime。

 extends: [
   'eslint:recommended',
   'plugin:react/recommended',
   'plugin:@typescript-eslint/recommended',
   'plugin:react/jsx-runtime'
 ],

此时App.tsx和main.tsx就不会报错了。

看到main.tsx文件带有警告颜色，看警告提示是Forbidden non-null assertion。

这个提示是不允许使用非空操作符!，但实际在项目中经常会用到，所以可以把该项校验给关闭掉。

在eslint配置文件 .eslint.js的rules字段添加插件 '@typescript-eslint/no-non-null-assertion': 'off'。

rules: {
    '@typescript-eslint/no-non-null-assertion': 'off'
  }

然后就不会报警告了，如果为了避免代码出现异常，不想关闭该校验，可以提前做判断

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

const root = document.getElementById('root')
// 如果root有值，才执行react渲染逻辑
if (root) {
  ReactDOM.createRoot(root).render(
    <React.StrictMode>
      <App />
    </React.StrictMode>

  )
}

.eslintec.js文件也有红色报错，报错是 'module' is not defined.

这个是因为上面选择的浏览器环境，配置文件的module.exports需要node环境，需要在eslint的env环境配置中添加支持node环境

env: {
    browser: true,
    es2021: true,
    node: true
  },

到这一步项目目前就没有报错了，在页面里面如果有定义了但未使用的变量，会有eslint的标黄效果提示，如果有语法问题也会警告或者报错提示，等后面出现了其他问题再按照情况进行修复或者调整eslint配置。

添加 eslint 语法检测脚本

前面的eslint报错和警告都是我们用眼睛看到的，有时候需要通过脚本执行能检测出来，在package.json的scripts中新增

"eslint": "eslint src/**/*.{ts,tsx}"

代表检测src目录下以**.ts**,.tsx为后缀的文件，然后在main.tsx里面定义一个未使用的变量a

执行 npm run eslint

除此之外再解决一个问题就是eslint报的警告React version not specified in eslint-plugin-react settings,需要告诉eslint使用的react版本，在 .eslintrc.js和rules平级添加settings配置，让eslint自己检测react版本,对应issuse

 settings: {
    "react": {
      "version": "detect"
    }
  }

再执行 npm run eslint就不会报这个未设置react版本的警告了。

配置 prettier

多人协作的项目开发中，保持统一的代码风格是一件很重要的事。
Prettier就可以帮我们做到这个事情，但是ESLint不是也能规范代码风格么？可以是可以，但是相比Prettier差了很多，术业有专攻，Prettier可以让我们拥有超级整齐的代码。可以帮助我们配置是否使用分号，缩进的格式等等。
官方文档：Prettier 中文网 · Prettier 是一个“有态度”的代码格式化工具

添加配置文件

Prettier配置文件名称可以为：.ptettierrc.js、.ptettier.config.js （根据个人习惯选择即可）
下面是我常用的一些配置，更多配置规则大家可以前官网查看：Options · Prettier 中文网

.prettierrc.js

module.exports = {
    printWidth: 120, //单行长度
    tabWidth: 2, //缩进长度
    useTabs: false, //使用空格代替tab缩进
    semi: true, //句末使用分号
    singleQuote: true, //使用单引号
    endOfLine: 'auto',
    // indent: 4, //缩进长度
    trailingComma: 'none' // 对象最后一个属性末尾是否要逗号
};

解决ESLint与Prettier冲突问题

安装 eslint-config-prettier  eslint-plugin-prettier 两个插件的目的就是为了解决 ESLint 与 Prettier 的冲突问题

在里extends 里新增配置：

extends: [
...
"prettier", 
],

配置完成之后我们对代码风格的配置只会使用prettier的配置，相当于将eslint中冲突的规则覆盖掉了。我们还可以配置忽略文件，让 Prettier 不对这些文件进行校验。

.prettierignor

/dist/*
/node_modules/**

配置 Husky

pnpm install -D husky

团队协作时，我们会遇到多种问题，最让人难受的就是每个人书写的代码风格不一致😅，使用的规范不一致，导致团队协作效率极低，代码可读性差。
这时候就需要 Husky 来帮忙了，它可以帮助我们在代码提交前后进行一些自定义的操作，像是代码风格的校验，并且它支持所有的 Git 钩子（钩子是你可以放在钩子目录中触发的程序在 Git 执行的某些点执行的操作）。
Git全部钩子的详细介绍：Git - githooks Documentation (git-scm.com)本文用到的钩子：
在 pre-commit 触发时进行代码格式验证，在 commit-msg 触发时对 commit 消息和提交用户进行验证。

git hook	执行时期	备注
pre-commit	git commit 执行前	git commit --no verify 命令可以绕过该钩子
commit-msg	git commit 执行前	git commit --no verify 命令可以绕过该钩子

安装好插件后，配置一个初始化 Hysky 的命令

// package.json
{
  "script": {
    "prepare": "husky install"
  }
}

然后，运行这个命令

# 运行后会初始化husky
pnpm run prepare

运行之后就会出现.husky文件夹，之后我们就可以配置在GItHook中执行的操作啦😀

.husky/commit-msg

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install commitlint --edit $1

.husky/pre-commit

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install lint-staged

.husky/_/husky.sh

#!/usr/bin/env sh
if [ -z "$husky_skip_init" ]; then
  debug () {
    if [ "$HUSKY_DEBUG" = "1" ]; then
      echo "husky (debug) - $1"
    fi
  }

  readonly hook_name="$(basename -- "$0")"
  debug "starting $hook_name..."

  if [ "$HUSKY" = "0" ]; then
    debug "HUSKY env variable is set to 0, skipping hook"
    exit 0
  fi

  if [ -f ~/.huskyrc ]; then
    debug "sourcing ~/.huskyrc"
    . ~/.huskyrc
  fi

  readonly husky_skip_init=1
  export husky_skip_init
  sh -e "$0" "$@"
  exitCode="$?"

  if [ $exitCode != 0 ]; then
    echo "husky - $hook_name hook exited with code $exitCode (error)"
  fi

  if [ $exitCode = 127 ]; then
    echo "husky - command not found in PATH=$PATH"
  fi

  exit $exitCode
fi

配置 LintStaged

在上面配置的eslint 会检测src文件下所有的 .ts, .tsx文件，虽然功能可以实现，但是当项目文件多的时候，检测的文件会很多，需要的时间也会越来越长，但其实只需要检测提交到暂存区，就是git add添加的文件，不在暂存区的文件不用再次检测，而lint-staged就是来帮我们做这件事情的。

pnpm install -D lint-staged

有时候我们会感觉使用IDE的保存自动修复相当麻烦，我每次改完之后都需要等他修复一下😡，太不方便啦！
接下来就要请出我们的好帮手：lint-staged，它可以帮助我们在 git 缓存中进行代码质量与风格的修复，在代码提交前进行统一校验，通过后才可以提交。

配置方式一：

修改package.json脚本eslint的配置

"eslint": "eslint"

在package.json添加lint-staged配置

"lint-staged": {
  "src/**/*.{ts,tsx}": [
    "npm run eslint"
  ]
},

因为要检测git暂存区代码，所以需要执行git init初始化一下git

git init

初始化git完成后就可以进行测试了，先提交一下没有语法问题的App.tsx

git add src/App.tsx

把src/App.tsx提交到暂存区后，执行npx lint-staged

可以看到检测通过了，没有检测到语法问题，再把有语法问题的src/main.tsx文件提交暂存区再检测一下看看

发现虽然main.tsx虽然有eslint语法警告，但依然验证成功了，是因为lint-staged只会检测到语法报错才会有提示只是警告不会，如果需要出现警告也阻止代码提交，需要给 eslint 检测配置参数 --max-warnings=0

 "eslint": "eslint --max-warnings=0"

代表允许最多0个警告，就是只要出现警告就会报错，修改完成后再次执行npx lint-staged

就会看到最终执行的命令是

eslint --max-warnings=0 "E:/wuyou/react/my-react-app/src/App.tsx" "E:/wuyou/react/my-react-app/src/main.tsx"

eslint只检测了 git 暂存区的App.tsx和main.tsx两个文件，做到了只检测git暂存区中文件的功能，避免每次都全量检测文件。

而添加了 --max-warnings=0 参数后，警告也可以检测出来并报错中断命令行了。

配置方式二：

在 package.json 配置一个指令方便我们使用

{
  "script":{
    "lint:lint-staged": "lint-staged",
  }
}

使用 husky 配置一个 pre-commit 钩子，运行以下命令即可

# --no-install 代表强制使用本地模块
npx husky add .husky/pre-commit "npm run lint:lint-staged"

LintStaged 的配置文件方式也有多种：

在 package.json 中配置
lint-staged.js 或 lint-staged.config.js
.lintstagedrc.json 或 .lintstagedrc.yaml

这里我们直接在 package.json 中配置

"lint-staged": {
  "**/src/*.{js,jsx,ts,tsx}": [
    "eslint --fix --ext .ts,.tsx"
  ],
  "*.{js,jsx,,md,json}": [
    "prettier --write"
  ],
  "*.ts?(x)": [
    "prettier --parser=typescript --write"
  ]
},

使用 tsc 检测类型和报错

在项目中使用了ts,但一些类型问题，现在配置的eslint是检测不出来的，需要使用ts提供的tsc工具进行检测，如下示例

在main.tsx定义了函数say,参数name是string类型，当调用传number类型参数时，页面有了明显的ts报错，但此时提交main.tsx文件到暂存区后执行npx lint-staged

发现没有检测到报错，所以需要配置下tsc来检测类型，在package.json添加脚本命令

"pre-check": "tsc && npx lint-staged"

执行npm run pre-check，发现已经可以检测出类型报错了。

配置 CommitLint 以及实现自定义提交规则

每次看 Github 仓库的时候，总感觉有些不顺眼。原来是提交附带的信息乱糟糟的，都是"新增xx功能"，"修复xxBUG"，非常的不工整，看着太不舒服啦🤯。
不要慌，我们可以使用 CommitLint 对提交的信息进行规范。
官方文档：commitlint - Lint commit messages

pnpm install commitizen commitlint commitlint-config-cz cz-customizable -D

在 package.json 里增加以下配置

"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
},

在项目根目录下新建以下配置文件

.commitlintrc.js

module.exports = {
  extends: ["cz"],
};

.cz-config.js

module.exports = {
  types: [
    { value: "feat", name: "✨ feat: 一个新的特性" },
    { value: "fix", name: "🐛 fix: 修复一个Bug" },
    { value: "docs", name: "📚 docs: 变更的只有文档" },
    { value: "style", name: "💎 style: 代码风格,格式修复" },
    { value: "config", name: "㊙️ config: 配置文件的变动" },
    {
      value: "refactor",
      name: "📦 refactor: 代码重构，注意和feat、fix区分开",
    },
    { value: "perf", name: "🚀 perf: 代码优化,改善性能" },
    { value: "test", name: "🚨 test: 测试" },
    { alue: "chore", name: "🍉 chore: 变更构建流程或辅助工具" },
    { value: "revert", name: "🌄 revert: 代码回退" },
    { value: "init", name: "🔰 init: 项目初始化" },
    { value: "build", name: "⭐ build: 变更项目构建或外部依赖" },
    { value: "WIP", name: "🚶 WIP: 进行中的工作" },
  ],
  scopes: [],
  allowTicketNumber: false,
  isTicketNumberRequired: false,
  ticketNumberPrefix: "TICKET-",
  ticketNumberRegExp: "\\d{1,5}",
  messages: {
    type: "选择一种你的提交类型:",
    scope: "选择一个scope (可选):",
    customScope: "Denote the SCOPE of this change:",
    subject: "简短说明(最多40个字):",
    body: '长说明，使用"|"换行(可选)：\n',
    breaking: "非兼容性说明 (可选):\n",
    footer: "关联关闭的issue，例如：#12, #34(可选):\n",
    confirmCommit: "确定提交?",
  },
  allowCustomScopes: true,
  allowBreakingChanges: ["feat", "fix"],
  skipQuestions: ["scope", "body", "breaking"],
  subjectLimit: 100,
};

钩子配置

# 配置 commit-msg 钩子 运行 commitlint
# --no-install 代表强制使用本地模块
npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"

配置完成后我们就可以在git commit时进行信息的规范我们需要按照以下格式进行

提交：

# 初始化仓库

git init 



# 添加到暂存区

git add -A



# 提交代码

pnpm cz

# 按照提示下一步就行，.cz-config.js可以修改提示相关配置



# 如果是第一次推送，那么应该 

git remote add origin xxxx.git



# 这里需要注意的是 gitee 上默认主分支是 master，但是在我的 mac 电脑上，默认的好像是 main

git push --set-upstream origin main

完整项目地址

地址：react18-admin-pro: 基于 react18 + vite5 + typeScript + commitLint + prettier + eslint + husky + lintStaged 实现后台管理系统基本框架

完整的 package.json

{
  "name": "react18-admin-pro",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@ant-design/icons": "^5.3.7",
    "@ant-design/plots": "^2.2.2",
    "@ant-design/pro-components": "^2.7.9",
    "@testing-library/jest-dom": "^5.17.0",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "@types/jest": "^29.5.12",
    "@types/node": "^20.14.1",
    "@types/react": "^18.3.3",
    "@types/react-dom": "^18.3.0",
    "antd": "^5.18.0",
    "axios": "^1.7.2",
    "dayjs": "^1.11.11",
    "lodash": "^4.17.21",
    "rc-resize-observer": "^1.4.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^6.23.1",
    "react-scripts": "5.0.1",
    "typescript": "^5.4.5",
    "vite-tsconfig-paths": "^4.3.2",
    "web-vitals": "^2.1.4",
    "zustand": "^4.5.2"
  },
  "scripts": {
    "start": "vite",
    "build": "vite build",
    "preview": "vite preview --port 8080",
    "prepare": "husky install",
    "lint:lint-staged": "lint-staged"
  },
  "lint-staged": {
    "**/src/*.{js,jsx,ts,tsx}": [
      "eslint --fix --ext .ts,.tsx"
    ],
    "*.{js,jsx,,md,json}": [
      "prettier --write"
    ],
    "*.ts?(x)": [
      "prettier --parser=typescript --write"
    ]
  },
  "config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "@faker-js/faker": "^8.4.1",
    "@typescript-eslint/eslint-plugin": "^7.12.0",
    "@typescript-eslint/parser": "^7.12.0",
    "@vitejs/plugin-react": "^4.3.0",
    "commitizen": "^4.3.0",
    "commitlint": "^19.3.0",
    "commitlint-config-cz": "^0.13.3",
    "cz-customizable": "^7.0.0",
    "eslint": "^9.4.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.1.3",
    "eslint-plugin-react": "^7.34.2",
    "husky": "^9.0.11",
    "lint-staged": "^15.2.5",
    "mockjs": "^1.1.0",
    "prettier": "^3.3.0",
    "sass": "^1.77.4",
    "vite": "^5.2.12",
    "vite-plugin-compression": "^0.5.1",
    "vite-plugin-mock": "^3.0.2"
  }
}