本文引用的文件
本仓库的前端位于 ai-electron/frontend,采用 Vue 3、TypeScript、Less/SCSS、Vite 和 UnoCSS 技术栈。代码质量由 ESLint、Stylelint、Prettier、TypeScript 类型检查共同保障:
该文档以 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
图表来源
章节来源
ESLint 在本项目中承担以下职责:
vue-eslint-parser 解析 .vue,并为 <template>、<script lang="ts">、JSX 配置不同子解析器。@typescript-eslint/parser 和 @typescript-eslint/eslint-plugin,但整体采用宽松模式。@babel/eslint-parser,支持装饰器等现代语法。eslint-plugin-prettier 把 Prettier 作为 ESLint 规则执行。章节来源
Stylelint 在本项目中承担以下职责:
postcss-html 解析 HTML 和 Vue 中的样式块。postcss-less 与 Less 推荐配置。postcss-scss 与 SCSS 推荐配置。stylelint-prettier 保持样式格式化一致性。inset,允许传统 top/right/bottom/left,并对伪类、伪元素、at-rule、单位等进行白名单管理。章节来源
Prettier 在本项目中是统一格式化引擎,被 ESLint 和 Stylelint 引用:
章节来源
下图展示前端代码质量工具的调用关系:
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"]
图表来源
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 更关注格式和样式。
章节来源
公共配置启用了:
no-undef、space-before-function-paren、no-case-declarations、no-extra-boolean-cast。这使 ESLint 能在多运行时环境中工作,同时避免对旧代码造成大量误报。
章节来源
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 模板规则"]
图表来源
章节来源
TypeScript 使用 @typescript-eslint/parser 和 @typescript-eslint/eslint-plugin,并继承 recommended 规则集。但后续又关闭了大量严格规则,包括:
ban-ts-commentban-typesexplicit-module-boundary-typesno-empty-functionno-explicit-anyno-non-null-assertionno-unused-expressionsno-unused-varsno-use-before-defineno-var-requiresno-unsafe-function-type因此当前 TypeScript 规则属于“有基础检查 + 宽松放宽”的组合,适合渐进式迁移或历史代码较多的项目。
flowchart TD
TSFiles["*.ts / *.tsx"] --> TSParser["@typescript-eslint/parser"]
TSParser --> TSPlugin["@typescript-eslint/eslint-plugin"]
TSPlugin --> Recommended["recommended 规则集"]
Recommended --> Overrides["宽松覆盖规则"]
图表来源
章节来源
JavaScript 文件使用 @babel/eslint-parser,并启用:
@babel/preset-env。@babel/plugin-proposal-decorators,legacy 模式。这使得 ESLint 可以检查包含装饰器的 JS 文件,但注意该配置没有额外启用业务级 ESLint 规则,主要依赖公共基础规则和 Prettier。
章节来源
ESLint 通过 eslint-plugin-prettier 将 Prettier 作为规则运行,配置项为:
| 选项 | 值 | 含义 |
|---|---|---|
printWidth |
120 |
最大行宽 120 |
semi |
true |
语句末尾必须加分号 |
singleQuote |
true |
优先使用单引号 |
trailingComma |
'all' |
所有可能的位置都加尾逗号 |
同时关闭了 property-sort-order,避免与现有对象属性排序习惯冲突。
章节来源
Stylelint 根配置启用:
stylelint-prettier:将 Prettier 应用到样式。stylelint-less:辅助 Less 处理。@stylistic/stylelint-plugin:提供风格化规则。extends 引入:
stylelint-config-standard:标准 CSS 规则。stylelint-config-standard-less:标准 Less 规则。忽略脚本文件:
**/*.js**/*.jsx**/*.tsx**/*.ts章节来源
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"]
图表来源
章节来源
Less 文件:
postcss-less。stylelint-config-recommended-less。SCSS 文件:
postcss-scss。stylelint-config-recommended-scss。stylelint-config-recommended-vue/scss,用于 Vue 内联 SCSS。章节来源
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"]
图表来源
章节来源
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
图表来源
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
图表来源
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 目录下执行。
| 命令 | 含义 | 适用场景 |
|---|---|---|
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 |
生产环境构建 | 打包部署 |
章节来源
推荐在 VS Code 中安装以下扩展:
eslint.config.mjs,实时提示 JS/TS/Vue 问题。.vue 文件语法高亮、片段和诊断。.prettierrc.mjs 进行格式化。stylelint.config.mjs,对样式文件进行检查。建议在用户设置中启用:
如果希望 Prettier 与 ESLint 冲突最小化,应保持 eslint-plugin-prettier 和 .prettierrc.mjs 的配置一致。
ai-electron/frontend/eslint.config.mjs。.prettierrc.mjs。ai-electron/frontend/stylelint.config.mjs。由于 lint:eslint 已经包含 --fix,可直接用命令批量修复可自动恢复的问题;对于需要人工判断的规则(如 TS 宽松规则),应结合 IDE 红色波浪线逐个处理。
现象:Stylelint 报出未知伪类或伪元素。
可能原因:使用了深度选择器或 Vue 组件穿透语法,但未在白名单中。
修复方法:
::v-deep、:deep()、:global() 等受支持的写法。stylelint.config.mjs 的 selector-pseudo-class-no-unknown 或 selector-pseudo-element-no-unknown 中添加。章节来源
现象:Stylelint 报出未知单位。
可能原因:使用了非标准单位。
修复方法:
rpx:已在 unit-no-unknown.ignoreUnits 中放行。ignoreUnits 中新增,谨慎评估是否真正需要。章节来源
inset 属性值非法现象:Stylelint 报出 inset 被禁用。
原因:配置中通过 declaration-property-value-disallowed-list 禁用了所有 inset 值。
修复方法:
top、right、bottom、left。inset,可调整该规则,但会削弱布局方向一致性。章节来源
现象: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 中添加。章节来源
现象:出现 any、unused vars、no use before define 等 TS 相关警告。
原因:虽然启用了 @typescript-eslint/recommended,但后续关闭了大量严格规则。
修复方法:
eslint.config.mjs 中移除对应 off,例如 no-explicit-any、no-unused-vars。章节来源
现象:Prettier 格式化后 ESLint 仍报错,或两者格式化结果不一致。
原因:ESLint 中 Prettier 规则配置与 .prettierrc.mjs 不一致。
修复方法:
eslint-plugin-prettier 的 options 与 .prettierrc.mjs 一致。printWidth=120、semi=true、singleQuote=true、trailingComma=all,与 Prettier 根配置保持一致。章节来源
现象:某些文件未触发 ESLint 或 Stylelint。
可能原因:
.prettierignore 或 .stylelintignore 忽略。lint:* 脚本的 glob 匹配范围内。修复方法:
node_modules、dist、public、build、.git 等忽略目录中。package.json 中 lint:eslint、lint:prettier、lint:stylelint 的 glob 是否覆盖目标文件。章节来源
假设要新增 Stylus 支持,可按以下步骤扩展:
stylelint.config.mjs 中注册自定义语法:在 overrides 中新增 *.styl 文件匹配。at-rule-no-unknown.ignoreAtRules。lint:stylelint 命令:确保 glob 能扫描到新后缀。参考现有 Less/SCSS 扩展:
customSyntax: 'postcss-less',继承 stylelint-config-recommended-less。customSyntax: 'postcss-scss',继承 stylelint-config-recommended-scss 和 Vue SCSS 推荐配置。章节来源
如果需要增加新的 Vue 规则:
eslint.config.mjs 的 Vue 配置段中新增规则键。error、warn 或 off。<template> 或 <script> 的不同行为,注意 Vue 解析器已区分子区域。当前 Vue 规则以关闭为主,仅保留 vue/html-self-closing 作为较明确的强制规则。新增规则时应避免与 Prettier 产生冲突。
章节来源
如果要收紧 TS 规则:
eslint.config.mjs 的 TS 配置段中移除对应 off。no-unused-vars、no-explicit-any、no-non-null-assertion。章节来源
如果要新增 Prettier 规则:
.prettierrc.mjs 中修改或新增选项。eslint-plugin-prettier 的 options。pnpm lint:prettier 和 pnpm lint:eslint 验证一致性。章节来源
node_modules、dist、public、build、.git 等已被忽略,避免检查生成文件或无关目录。pnpm lint:all,并在 CI 中将 --fix 替换为只读检查,防止自动修复掩盖真实问题。package.json 要求 Node >= 20.19 或 >= 22.12,本地环境应满足该要求。章节来源
本项目的代码质量工具链以 ESLint、Stylelint、Prettier 为核心,围绕 Vue、TypeScript、JavaScript、HTML、Less、SCSS 形成分层检查体系:
package.json 提供标准化命令,便于本地开发和持续集成。在实际协作中,建议:
pnpm lint:eslint 和 pnpm lint:stylelint。