前端代码规范与质量工具.md 29 KB

前端代码规范与质量工具

本文引用的文件

  • ai-electron/frontend/eslint.config.mjs
  • ai-electron/frontend/stylelint.config.mjs
  • ai-electron/frontend/package.json
  • ai-electron/frontend/.prettierrc.mjs
  • ai-electron/frontend/.prettierignore
  • ai-electron/frontend/.stylelintignore

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细配置分析
  6. 依赖关系分析
  7. 常用命令
  8. IDE 集成建议
  9. 常见报错与修复方法
  10. 扩展指南:新增样式语言或 Vue 规则
  11. 性能与稳定性注意事项
  12. 结论

引言

本仓库的前端位于 ai-electron/frontend,采用 Vue 3、TypeScript、Less/SCSS、Vite 和 UnoCSS 技术栈。代码质量由 ESLint、Stylelint、Prettier、TypeScript 类型检查共同保障:

  • ESLint 负责 JavaScript、TypeScript、Vue 文件的语法与风格检查。
  • Stylelint 负责 HTML、Vue、Less、SCSS 等样式相关文件的格式与规则检查。
  • Prettier 提供统一的代码格式化能力,并通过 ESLint 和 Stylelint 插件参与校验。
  • package.json scripts 提供统一的质量门禁入口,便于本地开发、持续集成和本地全量检查。

该文档以 eslint.config.mjs 和 stylelint.config.mjs 为核心,结合 package.json、.prettierrc.mjs、.prettierignore、.stylelintignore,说明解析器、插件、忽略路径、规则策略以及扩展方式。

项目结构

前端质量工具集中在 ai-electron/frontend 目录下,关键配置文件如下:

graph TB
  FE["前端根目录<br/>ai-electron/frontend"]
  ESLINT["eslint.config.mjs<br/>ESLint 配置"]
  STYLELINT["stylelint.config.mjs<br/>Stylelint 配置"]
  PKG["package.json<br/>脚本与依赖"]
  PRETTIER[".prettierrc.mjs<br/>Prettier 配置"]
  PRETTIER_IGNORE[".prettierignore<br/>Prettier 忽略列表"]
  STYLELINT_IGNORE[".stylelintignore<br/>Stylelint 忽略列表"]

  FE --> ESLINT
  FE --> STYLELINT
  FE --> PKG
  FE --> PRETTIER
  FE --> PRETTIER_IGNORE
  FE --> STYLELINT_IGNORE

图表来源

  • ai-electron/frontend/eslint.config.mjs:1-177
  • ai-electron/frontend/stylelint.config.mjs:1-121
  • ai-electron/frontend/package.json:1-162
  • ai-electron/frontend/.prettierrc.mjs:1-32
  • ai-electron/frontend/.prettierignore:1-14
  • ai-electron/frontend/.stylelintignore:1-6

章节来源

  • ai-electron/frontend/eslint.config.mjs:1-177
  • ai-electron/frontend/stylelint.config.mjs:1-121
  • ai-electron/frontend/package.json:1-162
  • ai-electron/frontend/.prettierrc.mjs:1-32
  • ai-electron/frontend/.prettierignore:1-14
  • ai-electron/frontend/.stylelintignore:1-6

核心组件

ESLint 核心职责

ESLint 在本项目中承担以下职责:

  1. 定义全局忽略路径:跳过构建产物、依赖包、版本控制元数据、二进制字体、快照等非源码文件。
  2. 提供公共基础规则:启用最新 ECMAScript、模块语法,并暴露浏览器与 Node.js 全局变量。
  3. 处理 Vue 文件:使用 vue-eslint-parser 解析 .vue,并为 <template>、<script lang="ts">、JSX 配置不同子解析器。
  4. 处理 TypeScript 文件:使用 @typescript-eslint/parser 和 @typescript-eslint/eslint-plugin,但整体采用宽松模式。
  5. 处理 JavaScript 文件:使用 @babel/eslint-parser,支持装饰器等现代语法。
  6. 集成 Prettier:通过 eslint-plugin-prettier 把 Prettier 作为 ESLint 规则执行。

章节来源

  • ai-electron/frontend/eslint.config.mjs:1-177

Stylelint 核心职责

Stylelint 在本项目中承担以下职责:

  1. 定义忽略的文件类型:忽略 JS、TS、TSX、JSX 等脚本文件。
  2. 支持 HTML/Vue 样式:使用 postcss-html 解析 HTML 和 Vue 中的样式块。
  3. 支持 Less:使用 postcss-less 与 Less 推荐配置。
  4. 支持 SCSS:使用 postcss-scss 与 SCSS 推荐配置。
  5. 集成 Prettier:通过 stylelint-prettier 保持样式格式化一致性。
  6. 约束 CSS 语义:禁用 inset,允许传统 top/right/bottom/left,并对伪类、伪元素、at-rule、单位等进行白名单管理。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:1-121

Prettier 核心职责

Prettier 在本项目中是统一格式化引擎,被 ESLint 和 Stylelint 引用:

  • 行宽为 120。
  • 分号必填。
  • 单引号优先。
  • 尾逗号全部开启。
  • Vue 中 script 和 style 块支持缩进。
  • JSON 配置文件按 JSON 语法格式化。
  • 忽略构建产物、锁文件、文档、SVG、HTML 等静态资源。

章节来源

  • ai-electron/frontend/.prettierrc.mjs:1-32
  • ai-electron/frontend/.prettierignore:1-14

架构总览

下图展示前端代码质量工具的调用关系:

flowchart TD
  Dev["开发者修改代码"] --> Scripts["package.json 脚本"]
  Scripts --> ESLintCmd["ESLint 检查 TS/TSX/MJS/VUE"]
  Scripts --> PrettierCmd["Prettier 检查 Vue/TSX/Less/SCSS"]
  Scripts --> StylelintCmd["Stylelint 检查 Vue/Less/SCSS/CSS"]
  ESLintCmd --> ESLintConfig["eslint.config.mjs"]
  PrettierCmd --> PrettierConfig[".prettierrc.mjs"]
  StylelintCmd --> StylelintConfig["stylelint.config.mjs"]
  ESLintConfig --> ParserVue["vue-eslint-parser"]
  ESLintConfig --> ParserTS["@typescript-eslint/parser"]
  ESLintConfig --> ParserBabel["@babel/eslint-parser"]
  StylelintConfig --> PostcssHtml["postcss-html"]
  StylelintConfig --> PostcssLess["postcss-less"]
  StylelintConfig --> PostcssScss["postcss-scss"]

图表来源

  • ai-electron/frontend/package.json:1-162
  • ai-electron/frontend/eslint.config.mjs:1-177
  • ai-electron/frontend/stylelint.config.mjs:1-121
  • ai-electron/frontend/.prettierrc.mjs:1-32

详细配置分析

ESLint 配置分析

忽略路径

ESLint 在顶层 ignores 中跳过以下路径:

类别 忽略模式 目的
依赖包 **/node_modules/ 不检查第三方库
构建输出 **/dist/ 不检查打包产物
静态资源 **/public/ 不检查公开静态目录
构建脚本目录 **/build/ 不检查构建目录
版本控制 **/.git/ 不检查 Git 元数据
IDE 配置 **/.vscode/、**/.idea/ 不检查编辑器配置
钩子目录 **/.husky/ 不检查 Git hooks
本地缓存 **/.local/、**/.turbo/ 不检查本地缓存
容器镜像 **/Dockerfile 不检查 Docker 文件
Shell 脚本 **/*.sh 不检查 Shell 脚本
文档 **/*.md 不检查 Markdown
字体 **/*.woff、**/*.ttf 不检查字体文件
类型声明 **/*.d.ts 不检查 d.ts
测试快照 **/__snapshots__/ 不检查快照

这些忽略路径与 .prettierignore、.stylelintignore 的忽略策略相互补充:ESLint 更关注可执行代码,Prettier 和 Stylelint 更关注格式和样式。

章节来源

  • ai-electron/frontend/eslint.config.mjs:13-33

公共基础配置

公共配置启用了:

  • 最新 ECMAScript 语法。
  • ES Module 模块系统。
  • 浏览器和 Node.js 全局变量。
  • 关闭部分过于严格或不必要的通用规则,例如 no-undef、space-before-function-paren、no-case-declarations、no-extra-boolean-cast。

这使 ESLint 能在多运行时环境中工作,同时避免对旧代码造成大量误报。

章节来源

  • ai-electron/frontend/eslint.config.mjs:35-56

Vue 文件解析与规则

Vue 文件使用 vue-eslint-parser 解析,并进一步为不同子区域配置解析器:

子区域 解析器 说明
<script lang="ts"> @typescript-eslint/parser 使用 TypeScript 解析
JSX/TSX @typescript-eslint/parser 启用 JSX 支持
普通 JS @babel/eslint-parser 支持装饰器等现代语法
<template> espree 使用 ESPree 解析模板 HTML

Vue 规则大部分被显式关闭,原因通常是团队尚未强制统一组件命名、属性顺序、单文件组件数量、自闭合标签等风格;而 vue/html-self-closing 仍保留为错误级别,要求 void 元素、组件元素和 SVG/MathML 使用自闭合写法。

flowchart TD
  VueFile[".vue 文件"] --> Template["<template><br/>ESPREE 解析"]
  VueFile --> ScriptTS["<script lang='ts'><br/>@typescript-eslint/parser"]
  VueFile --> ScriptJS["<script><br/>@babel/eslint-parser"]
  ScriptTS --> TSESLint["@typescript-eslint 规则"]
  ScriptJS --> BabelRules["Babel 解析规则"]
  Template --> VueRules["Vue 模板规则"]

图表来源

  • ai-electron/frontend/eslint.config.mjs:58-103

章节来源

  • ai-electron/frontend/eslint.config.mjs:58-103

TypeScript 配置

TypeScript 使用 @typescript-eslint/parser 和 @typescript-eslint/eslint-plugin,并继承 recommended 规则集。但后续又关闭了大量严格规则,包括:

  • ban-ts-comment
  • ban-types
  • explicit-module-boundary-types
  • no-empty-function
  • no-explicit-any
  • no-non-null-assertion
  • no-unused-expressions
  • no-unused-vars
  • no-use-before-define
  • no-var-requires
  • no-unsafe-function-type

因此当前 TypeScript 规则属于“有基础检查 + 宽松放宽”的组合,适合渐进式迁移或历史代码较多的项目。

flowchart TD
  TSFiles["*.ts / *.tsx"] --> TSParser["@typescript-eslint/parser"]
  TSParser --> TSPlugin["@typescript-eslint/eslint-plugin"]
  TSPlugin --> Recommended["recommended 规则集"]
  Recommended --> Overrides["宽松覆盖规则"]

图表来源

  • ai-electron/frontend/eslint.config.mjs:105-137

章节来源

  • ai-electron/frontend/eslint.config.mjs:105-137

JavaScript 配置

JavaScript 文件使用 @babel/eslint-parser,并启用:

  • @babel/preset-env。
  • @babel/plugin-proposal-decorators,legacy 模式。

这使得 ESLint 可以检查包含装饰器的 JS 文件,但注意该配置没有额外启用业务级 ESLint 规则,主要依赖公共基础规则和 Prettier。

章节来源

  • ai-electron/frontend/eslint.config.mjs:139-155

Prettier 集成

ESLint 通过 eslint-plugin-prettier 将 Prettier 作为规则运行,配置项为:

选项 值 含义
printWidth 120 最大行宽 120
semi true 语句末尾必须加分号
singleQuote true 优先使用单引号
trailingComma 'all' 所有可能的位置都加尾逗号

同时关闭了 property-sort-order,避免与现有对象属性排序习惯冲突。

章节来源

  • ai-electron/frontend/eslint.config.mjs:157-177
  • ai-electron/frontend/.prettierrc.mjs:1-32

Stylelint 配置分析

根配置与插件

Stylelint 根配置启用:

  • stylelint-prettier:将 Prettier 应用到样式。
  • stylelint-less:辅助 Less 处理。
  • @stylistic/stylelint-plugin:提供风格化规则。

extends 引入:

  • stylelint-config-standard:标准 CSS 规则。
  • stylelint-config-standard-less:标准 Less 规则。

忽略脚本文件:

  • **/*.js
  • **/*.jsx
  • **/*.tsx
  • **/*.ts

章节来源

  • ai-electron/frontend/stylelint.config.mjs:1-15

HTML 与 Vue 样式

HTML 和 Vue 文件使用 postcss-html 作为自定义语法,并继承 stylelint-config-recommended-vue。

针对 Vue 的特殊伪类和伪元素,配置了白名单:

类型 白名单 用途
伪类 global、deep 兼容深度选择器
伪元素 v-deep、v-global、v-slotted 兼容 Vue 深度作用域

此外,根 rules 中还保留了 v-deep 的伪元素白名单,作为额外兜底。

flowchart TD
  HTMLVue["HTML / Vue 文件"] --> PostcssHtml["postcss-html"]
  PostcssHtml --> VueRecommended["stylelint-config-recommended-vue"]
  VueRecommended --> PseudoClass["伪类白名单<br/>global, deep"]
  VueRecommended --> PseudoElement["伪元素白名单<br/>v-deep, v-global, v-slotted"]

图表来源

  • ai-electron/frontend/stylelint.config.mjs:16-34

章节来源

  • ai-electron/frontend/stylelint.config.mjs:16-34

Less 与 SCSS

Less 文件:

  • 使用 postcss-less。
  • 继承 stylelint-config-recommended-less。

SCSS 文件:

  • 使用 postcss-scss。
  • 继承 stylelint-config-recommended-scss。
  • 继承 stylelint-config-recommended-vue/scss,用于 Vue 内联 SCSS。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:35-46

样式规则策略

Stylelint 的规则体现“宽松但有边界”的策略:

规则或配置 行为 说明
prettier/prettier 开启,并限制位置简写、溢出简写 与 Prettier 保持一致
media-feature-range-notation null 关闭范围表示法检查
selector-not-notation null 关闭 not 选择器表示法检查
import-notation null 关闭 import 表示法检查
function-no-unknown null 允许未知函数,方便 UnoCSS、框架扩展
selector-class-pattern null 不强制类名命名模式
at-rule-prelude-no-invalid null 降低 at-rule 前缀严格度
declaration-property-value-no-unknown null 允许未知属性值
declaration-property-value-keyword-no-deprecated null 允许已废弃关键字
declaration-property-value-disallowed-list.inset 禁止所有 inset 值 明确禁用 inset
declaration-property-value-allowed-list.top/right/bottom/left 允许任意值 允许传统方位属性
selector-pseudo-class-no-unknown 白名单 global、deep 允许深度伪类
selector-pseudo-element-no-unknown 白名单 v-deep 允许 Vue 深度伪元素
at-rule-no-unknown 白名单多个 at-rule 兼容 Less/SCSS/UnoCSS
unit-no-unknown 白名单 rpx 允许 rpx 单位
flowchart TD
  Styles["样式代码"] --> Standard["stylelint-config-standard"]
  Styles --> LessExt["Less/SCSS 扩展"]
  Standard --> Rules["样式规则"]
  Rules --> Inset["禁用 inset"]
  Rules --> Position["允许 top/right/bottom/left"]
  Rules --> Units["允许 rpx"]
  Rules --> Pseudo["允许 global/deep/v-deep"]
  Rules --> AtRule["允许 Less/SCSS/UnoCSS at-rule"]

图表来源

  • ai-electron/frontend/stylelint.config.mjs:47-121

章节来源

  • ai-electron/frontend/stylelint.config.mjs:47-121

依赖关系分析

ESLint 依赖关系

graph TB
  ESLint["ESLint"]
  VuePlugin["eslint-plugin-vue"]
  TSESLint["@typescript-eslint/eslint-plugin"]
  PrettierPlugin["eslint-plugin-prettier"]
  TSParser["@typescript-eslint/parser"]
  VueParser["vue-eslint-parser"]
  BabelParser["@babel/eslint-parser"]
  Globals["globals"]

  ESLint --> VuePlugin
  ESLint --> TSESLint
  ESLint --> PrettierPlugin
  ESLint --> TSParser
  ESLint --> VueParser
  ESLint --> BabelParser
  ESLint --> Globals

图表来源

  • ai-electron/frontend/eslint.config.mjs:10-17

Stylelint 依赖关系

graph TB
  Stylelint["Stylelint"]
  StylelintPrettier["stylelint-prettier"]
  StylelintLess["stylelint-less"]
  Stylistic["@stylistic/stylelint-plugin"]
  Standard["stylelint-config-standard"]
  StandardLess["stylelint-config-standard-less"]
  PostcssHtml["postcss-html"]
  PostcssLess["postcss-less"]
  PostcssScss["postcss-scss"]

  Stylelint --> StylelintPrettier
  Stylelint --> StylelintLess
  Stylelint --> Stylistic
  Stylelint --> Standard
  Stylelint --> StandardLess
  Stylelint --> PostcssHtml
  Stylelint --> PostcssLess
  Stylelint --> PostcssScss

图表来源

  • ai-electron/frontend/stylelint.config.mjs:11-14

package.json 角色

package.json 定义了三个关键质量命令:

脚本 作用 扫描范围
lint:eslint ESLint 检查并自动修复 *.ts、*.tsx、*.mjs、*.vue
lint:prettier Prettier 检查和自动写入 *.vue、*.tsx、*.less、*.scss
lint:stylelint Stylelint 检查并自动修复 *.vue、*.less、*.scss、*.css
lint:all 完整流水线 安装依赖、类型检查、ESLint、Prettier、Stylelint

章节来源

  • ai-electron/frontend/package.json:1-32

常用命令

以下命令均在 ai-electron/frontend 目录下执行。

命令 含义 适用场景
pnpm lint:eslint 检查并尝试自动修复 JS/TS/Vue 问题 日常提交前检查
pnpm lint:prettier 检查并格式化 Prettier 支持的样式和前端文件 统一格式
pnpm lint:stylelint 检查并自动修复样式问题 Less/SCSS/Vue 样式检查
pnpm lint:all 安装依赖、类型检查、ESLint、Prettier、Stylelint 全流程 CI 或完整自检
pnpm type:check 使用 vue-tsc 做 TypeScript 类型检查 类型问题定位
pnpm dev 启动 Vite 开发服务器 日常开发
pnpm build 生产环境构建 打包部署

章节来源

  • ai-electron/frontend/package.json:5-16

IDE 集成建议

VS Code

推荐在 VS Code 中安装以下扩展:

  1. ESLint:自动读取 eslint.config.mjs,实时提示 JS/TS/Vue 问题。
  2. Vue - Official:支持 .vue 文件语法高亮、片段和诊断。
  3. Prettier - Code formatter:配合 .prettierrc.mjs 进行格式化。
  4. Stylelint:读取 stylelint.config.mjs,对样式文件进行检查。
  5. TypeScript Vue Plugin:提升 Vue + TS 的类型体验。

建议在用户设置中启用:

  • 保存时格式化。
  • 保存时运行 ESLint 自动修复。
  • 保存时运行 Prettier。
  • 打开 Vue 文件时启用 TypeScript 诊断。

如果希望 Prettier 与 ESLint 冲突最小化,应保持 eslint-plugin-prettier 和 .prettierrc.mjs 的配置一致。

WebStorm / PhpStorm

  1. 在项目设置中启用 ESLint,指向 ai-electron/frontend/eslint.config.mjs。
  2. 启用 Prettier,并关联项目根 .prettierrc.mjs。
  3. 启用 Stylelint,指向 ai-electron/frontend/stylelint.config.mjs。
  4. 在“保存时操作”中勾选格式化文件和运行 ESLint 检查。

命令行与编辑器联动

由于 lint:eslint 已经包含 --fix,可直接用命令批量修复可自动恢复的问题;对于需要人工判断的规则(如 TS 宽松规则),应结合 IDE 红色波浪线逐个处理。

常见报错与修复方法

1. 报告未识别的伪类或伪元素

现象:Stylelint 报出未知伪类或伪元素。

可能原因:使用了深度选择器或 Vue 组件穿透语法,但未在白名单中。

修复方法:

  • 使用 ::v-deep、:deep()、:global() 等受支持的写法。
  • 如需新增白名单,可在 stylelint.config.mjs 的 selector-pseudo-class-no-unknown 或 selector-pseudo-element-no-unknown 中添加。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:16-34
  • ai-electron/frontend/stylelint.config.mjs:84-98

2. 报告未知单位

现象:Stylelint 报出未知单位。

可能原因:使用了非标准单位。

修复方法:

  • 使用 rpx:已在 unit-no-unknown.ignoreUnits 中放行。
  • 使用其他单位:需在 ignoreUnits 中新增,谨慎评估是否真正需要。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:114-114

3. 报告 inset 属性值非法

现象:Stylelint 报出 inset 被禁用。

原因:配置中通过 declaration-property-value-disallowed-list 禁用了所有 inset 值。

修复方法:

  • 改为使用 top、right、bottom、left。
  • 如果确实需要 inset,可调整该规则,但会削弱布局方向一致性。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:72-82

4. 报告未知 at-rule

现象:Stylelint 报出未知 at-rule,例如 UnoCSS、Less、SCSS 指令。

可能原因:at-rule 不在 at-rule-no-unknown.ignoreAtRules 白名单中。

修复方法:

  • 优先使用已允许的指令,如 extends、ignores、include、mixin、if、else、media、for、at-root、unocss、apply、variants、responsive、screen、function、each、use、forward、return。
  • 确需新增指令时,在 at-rule-no-unknown 的 ignoreAtRules 中添加。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:99-112

5. ESLint 报 TS 相关警告

现象:出现 any、unused vars、no use before define 等 TS 相关警告。

原因:虽然启用了 @typescript-eslint/recommended,但后续关闭了大量严格规则。

修复方法:

  • 如果是临时遗留代码,保持现状即可。
  • 如果要逐步收紧,可在 eslint.config.mjs 中移除对应 off,例如 no-explicit-any、no-unused-vars。

章节来源

  • ai-electron/frontend/eslint.config.mjs:105-137

6. Prettier 与 ESLint 冲突

现象:Prettier 格式化后 ESLint 仍报错,或两者格式化结果不一致。

原因:ESLint 中 Prettier 规则配置与 .prettierrc.mjs 不一致。

修复方法:

  • 确保 eslint-plugin-prettier 的 options 与 .prettierrc.mjs 一致。
  • 本项目中 ESLint 配置为 printWidth=120、semi=true、singleQuote=true、trailingComma=all,与 Prettier 根配置保持一致。

章节来源

  • ai-electron/frontend/eslint.config.mjs:157-177
  • ai-electron/frontend/.prettierrc.mjs:1-32

7. 文件未被检查

现象:某些文件未触发 ESLint 或 Stylelint。

可能原因:

  • 文件被 ESLint ignores 忽略。
  • 文件被 .prettierignore 或 .stylelintignore 忽略。
  • 文件不在 lint:* 脚本的 glob 匹配范围内。

修复方法:

  • 确认文件是否在 node_modules、dist、public、build、.git 等忽略目录中。
  • 检查 package.json 中 lint:eslint、lint:prettier、lint:stylelint 的 glob 是否覆盖目标文件。
  • 如确需加入检查,从忽略列表中移除相应模式。

章节来源

  • ai-electron/frontend/eslint.config.mjs:13-33
  • ai-electron/frontend/.prettierignore:1-14
  • ai-electron/frontend/.stylelintignore:1-6
  • ai-electron/frontend/package.json:10-16

扩展指南:新增样式语言或 Vue 规则

新增一种样式语言

假设要新增 Stylus 支持,可按以下步骤扩展:

  1. 安装依赖:安装对应的 Stylelint 自定义语法插件。
  2. 在 stylelint.config.mjs 中注册自定义语法:在 overrides 中新增 *.styl 文件匹配。
  3. 选择合适的基础配置:例如使用官方推荐配置或项目已有 Less/SCSS 配置作为参考。
  4. 评估 at-rule 白名单:确认新语言的 at-rule 是否需要加入 at-rule-no-unknown.ignoreAtRules。
  5. 更新 lint:stylelint 命令:确保 glob 能扫描到新后缀。

参考现有 Less/SCSS 扩展:

  • Less:customSyntax: 'postcss-less',继承 stylelint-config-recommended-less。
  • SCSS:customSyntax: 'postcss-scss',继承 stylelint-config-recommended-scss 和 Vue SCSS 推荐配置。

章节来源

  • ai-electron/frontend/stylelint.config.mjs:35-46
  • ai-electron/frontend/stylelint.config.mjs:99-112
  • ai-electron/frontend/package.json:14-16

新增一种 Vue 规则

如果需要增加新的 Vue 规则:

  1. 在 eslint.config.mjs 的 Vue 配置段中新增规则键。
  2. 根据业务需求设置为 error、warn 或 off。
  3. 如果是组件命名、属性顺序、事件命名等强一致规则,建议先小范围试点,再全局推广。
  4. 若涉及 <template> 或 <script> 的不同行为,注意 Vue 解析器已区分子区域。

当前 Vue 规则以关闭为主,仅保留 vue/html-self-closing 作为较明确的强制规则。新增规则时应避免与 Prettier 产生冲突。

章节来源

  • ai-electron/frontend/eslint.config.mjs:58-103

新增 TypeScript 规则

如果要收紧 TS 规则:

  1. 在 eslint.config.mjs 的 TS 配置段中移除对应 off。
  2. 建议从低风险规则开始,例如 no-unused-vars、no-explicit-any、no-non-null-assertion。
  3. 对大型历史项目,建议分批推进,避免一次性引发大量 CI 失败。

章节来源

  • ai-electron/frontend/eslint.config.mjs:105-137

新增 Prettier 规则

如果要新增 Prettier 规则:

  1. 在 .prettierrc.mjs 中修改或新增选项。
  2. 同步更新 ESLint 中 eslint-plugin-prettier 的 options。
  3. 运行 pnpm lint:prettier 和 pnpm lint:eslint 验证一致性。

章节来源

  • ai-electron/frontend/.prettierrc.mjs:1-32
  • ai-electron/frontend/eslint.config.mjs:157-177

性能与稳定性注意事项

  1. 缓存:ESLint 和 Stylelint 均启用缓存,可减少重复检查成本。
  2. 忽略路径:node_modules、dist、public、build、.git 等已被忽略,避免检查生成文件或无关目录。
  3. 宽松规则:TS 和样式层存在较多 null 或白名单,可降低历史代码迁移成本,但也意味着代码质量门槛较低。
  4. CI 建议:生产环境建议使用 pnpm lint:all,并在 CI 中将 --fix 替换为只读检查,防止自动修复掩盖真实问题。
  5. Node 版本:package.json 要求 Node >= 20.19 或 >= 22.12,本地环境应满足该要求。

章节来源

  • ai-electron/frontend/package.json:1-L162

结论

本项目的代码质量工具链以 ESLint、Stylelint、Prettier 为核心,围绕 Vue、TypeScript、JavaScript、HTML、Less、SCSS 形成分层检查体系:

  • ESLint 负责 JS/TS/Vue 的可执行代码检查,解析器分工明确,规则整体宽松。
  • Stylelint 负责样式层检查,基于标准配置,并通过白名单适配 Vue、Less、SCSS、UnoCSS。
  • Prettier 提供统一格式化,并通过 ESLint 和 Stylelint 插件贯穿前端代码。
  • package.json 提供标准化命令,便于本地开发和持续集成。

在实际协作中,建议:

  • 日常开发使用 IDE 实时提示。
  • 提交前至少运行 pnpm lint:eslint 和 pnpm lint:stylelint。
  • 新增规则前先评估历史代码影响。
  • 对 TS 和 Vue 规则采取渐进收紧策略。
  • 对样式语言扩展遵循已有 Less/SCSS 模式。