Umi Lint 指南基于 ESLint 与 Stylelint 的开箱即用编码规范实践【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umiUmi 在框架内提供了开箱即用的 Lint 能力通过统一的umi lintCLI 集成 ESLint 与 Stylelint帮助团队以低成本、高性能、更稳定的方式把控制作质量。本文以官方指南 docs/docs/docs/guides/lint.md 为核心结合 packages/lint 包的源码实现完整讲解安装接入、配置继承、CLI 参数、Git 工作流集成与内置规则细节读完后你可以直接在 Umi / Umi Max 项目中落地一套与 Prettier 不冲突、规则稳定的编码规范方案。Umi Lint 的三个核心特性Umi 提供 Lint 能力的出发点是让开发者不必手动拼装 ESLint、Stylelint 及其插件、parser、冲突处理等大量配置而是直接获得一套经过筛选的推荐配置与统一入口推荐配置提供 ESLint 及 Stylelint 推荐配置可直接继承使用统一的 CLI提供umi lint命令集成式调用 ESLint 和 Stylelint规则稳定始终确保规则的稳定性不会因上游配置更新而导致存量项目 lint 失败。其中 ESLint 配置具备以下三个特点仅质量相关从数百条规则中筛选出数十条与编码质量相关的规则进行白名单开启回归 Lint 本质且不会与 Prettier 的规则冲突格式化交给 PrettierLint 只负责质量性能优先部分 TypeScript 规则实用性低但项目全量编译成本高对这些规则进行禁用以提升性能内置常用插件包含react、react-hooks、typescript-eslint、jest满足日常开发所需。此外Stylelint 配置还内置 CSS-in-JS 支持可以检测出 JS/TS 文件中样式表如 styled-components 模板字符串的语法错误。ESLint 推荐配置的源码级解析umi/eslint指向的核心配置位于 packages/lint/src/config/eslint/index.ts其整体结构如下parser使用babel/eslint-parser并通过parserOptions.babelOptions注入umijs/babel-preset-umi确保 Babel 相关语法能被正确解析同时requireConfigFile: false表示无需单独提供 Babel 配置文件env声明browser、node、es2022、jest环境settingsreact.version detect自动探测项目中的 React 版本overrides对**/*.{ts,tsx}文件切换为typescript-eslint/parser并启用 TS 规则对**/*.{test,spec,unit,e2e}.{ts,tsx,js,jsx}测试文件启用 jest 规则并通过detectJestVersion()见 packages/lint/src/config/eslint/index.ts探测项目实际安装的 jest 版本探测失败时回退为 29。推荐规则白名单具体开启的规则定义在 packages/lint/src/config/eslint/rules/recommended.ts全部为2即 error 级别。ESLint 内置部分节选规则作用eqeqeq强制使用/!避免潜在的类型转换问题no-eval禁止eval()避免潜在的安全问题no-debugger禁止debugger语句no-var禁止使用varguard-for-infor...in必须配合hasOwnProperty判断避免多出原型链内容no-param-reassign禁止修改函数入参防止意外影响原对象no-async-promise-executor禁止把 async 函数作为 Promise executorarray-callback-return要求数组回调必须返回React / React Hooks 部分节选规则作用react/button-has-typebutton 必须显式声明type规避默认submit行为react/jsx-keyJSX 列表必须提供keyreact/jsx-no-target-blank禁止target_blank不带relnoreferrerreact/no-deprecated禁止使用已废弃的 React APIreact-hooks/rules-of-hooks强制 Hooks 调用规则TypeScript 部分节选typescript-eslint/no-unused-vars、no-namespace、no-non-null-asserted-optional-chain、ban-types等。需要说明的是这些 TS 规则刻意避开了no-non-null-assertion感叹号断言等全量编译成本高、实用性低的规则这正是“性能优先”原则的体现。jest 部分节选jest/no-focused-tests禁止.only、jest/no-identical-title禁止重复标题、jest/valid-expect、jest/no-standalone-expect等。插件解析补丁packages/lint/src/config/eslint/setup.ts 通过rushstack/eslint-patch的modern-module-resolution补丁修正 ESLint 插件解析逻辑保证插件、parser 在 monorepo / workspace 场景下能被正确解析对应编译产物位于 packages/lint/compiled/rushstack/eslint-patch。仓库中还保留了基于旧版umijs/fabric规则的 legacy.ts 配置供需要兼容旧规则集的场景参考。Stylelint 推荐配置与 CSS-in-JS 支持umi/stylelint的核心配置位于 packages/lint/src/config/stylelint/index.ts规则迁移自umijs/fabric的 stylelint 配置extendsstylelint-config-standardstylelint-config-prettierstylelint-config-css-modules后两者为内置编译版本位于 packages/lint/compiledplugin启用stylelint-declaration-block-no-ignored-properties检测被其他属性覆盖而失效的 CSS 声明customSyntax使用内置的postcss-less原生支持 Less 语法overrides对**/*.{js,jsx,ts,tsx}文件切换为stylelint/postcss-css-in-js语法解析器——这就是“Stylelint 内置 CSS-in-JS 支持”的实现来源即开即用无需额外配置。关键 rules 说明规则取值说明selector-class-patternkebab-case 或 lowerCamelCase强制类名风格统一declaration-property-value-disallowed-list禁止单写 PingFangSC防止从 Sketch 无意识复制的字体规则在无该字体的设备上渲染异常unit-no-unknownignoreUnits: [rpx]放行小程序单位 rpxfont-family-no-missing-generic-family-keywordnull兼容 iconfont 场景selector-type-no-unknownnull兼容 Web Component 自定义标签no-descending-specificitynull关闭特异性降序检查减少误报接入步骤1. 安装依赖为节省安装体积目前仅在Umi Max中内置了 Lint 模块直接使用max lint执行即可如果使用的是Umi需要先安装umijs/lint$ npm i umijs/lint -D # or $ pnpm add umijs/lint -D然后安装 ESLint 与 Stylelint。注意目前umijs/lint使用的stylelint版本是 v14需要按版本指定安装$ npm i -D eslint stylelint^14 # or $ pnpm add -D eslint stylelint^14可以参考仓库中的 examples/lint/package.jsondevDependencies中eslint为^8.35.0、stylelint为^14.8.2并提供了lint、lint:es、lint:style、lint:cssinjs、lint:es-fix、lint:style-fix等可直接复用的 npm scripts。2. 继承推荐配置在项目根目录创建.eslintrc.js与.stylelintrc.js并继承 Umi 提供的配置// .eslintrc.js module.exports { // Umi 项目 extends: require.resolve(umi/eslint), // Umi Max 项目 extends: require.resolve(umijs/max/eslint), } // .stylelintrc.js module.exports { // Umi 项目 extends: require.resolve(umi/stylelint), // Umi Max 项目 extends: require.resolve(umijs/max/stylelint), }配置文件创建完毕后其实已经可以直接使用eslint、stylelint命令执行检查但官方仍推荐使用umi lint命令以获得更便捷的体验。umi lintCLI 用法命令形式如下$ umi lint [glob] [--fix] [--eslint-only] [--stylelint-only] [--cssinjs]参数说明参数说明[glob]可选指定要 lint 的文件默认为{src,test}/**/*.{js,jsx,ts,tsx,css,less}--quiet可选禁用warn规则的报告仅输出error--fix可选自动修复 lint 错误--eslint-only可选仅执行 ESLint--stylelint-only可选仅执行 Stylelint--cssinjs可选为 Stylelint 启用 CSS-in-JS 支持通常直接执行umi lint就能满足大部分场景。从源码看packages/lint/src/index.ts 是统一调度入口未指定--eslint-only时创建StyleLinter执行 Stylelint并通过--ignore-pattern排除**/*.{js,jsx,ts,tsx}只有显式传入--cssinjs才不排除这些文件即由 Stylelint 一并检查 JS 中的样式未指定--stylelint-only时创建EsLinter执行 ESLint并通过--ignore-pattern排除**/*.{less,css,sass,scss,styl}等样式文件两个 linter 并行通过子进程 fork 执行互不阻塞。Linter 的底层实现位于 packages/lint/src/linter/base.ts通过child_process.fork拉起对应 linter 的 bin 文件getBinPath通过require.resolve定位安装包内的 bin 入口找不到时抛出“please install it first”的明确提示并将子进程退出码透传到当前进程从而保证 CI 场景下 lint 失败能正确阻断流程。ESLint 子进程参数由 eslint.ts 组装透传--quiet、--fix及 globStylelint 子进程参数由 stylelint.ts 组装额外附带--config-basedir指向项目 cwd 以及--allow-empty-input。与 Git 工作流结合lint-staged Husky官方推荐使用 lint-staged 与 Husky将umi lint与 Git 工作流结合做到提交代码时自动 lint本次变更的代码兼顾编码质量与执行效率。lint-staged只检查本次变更lint-staged 用来驱动umi lint命令每次仅将暂存区中变更的内容交给umi lint检查。安装$ npm i lint-staged -D #or $ pnpm add lint-staged -D在package.json中配置{ lint-staged: { *.{js,jsx,ts,tsx,css,less}: [ umi lint ] } }配置完成后执行git add sample.js再执行npx lint-staged就能实现仅检查sample.js的本次变更。Husky绑定 Git HooksHusky 用来绑定 Git Hooks在指定时机例如pre-commit执行我们想要的命令安装方式参考 Husky 官方文档。初始化完成后手动修改.husky/pre-commit文件#!/bin/sh . $(dirname $0)/_/husky.sh - npm test npx lint-staged至此大功告成每次执行git commit时umi lint会自动对本次变更代码执行检查在确保编码质量的同时保证执行效率。与 Prettier 配合在启用umi lint的基础上官方也建议与 Prettier 一同使用以确保团队的代码风格基本一致。由于 Umi 的 ESLint 规则只关注质量、不包含格式化规则二者职责清晰、互不冲突可将 Prettier 按官方文档配置到 lint-staged 的同一组文件匹配中例如{ lint-staged: { *.{js,jsx,ts,tsx,css,less}: [ prettier --write, umi lint ] } }附录内置规则与配置的源码位置ESLint 推荐规则列表含每条规则开启原因注释packages/lint/src/config/eslint/rules/recommended.tsESLint 完整配置parser、env、overridespackages/lint/src/config/eslint/index.tsStylelint 配置extends、rules、CSS-in-JS overridepackages/lint/src/config/stylelint/index.tsLint 调度入口与 CLI 参数处理packages/lint/src/index.tsLinter 子进程执行与退出码透传packages/lint/src/linter/base.ts可直接运行的示例项目examples/lint/package.json内含lint:es、lint:style、lint:cssinjs等脚本以及 examples/lint/src 下的测试用例文件【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考