web-code-lint

一站式前端代码规范工具（2.0），一键集成：

• ESLint 9（flat config）+ Vue <template> + TypeScript
• Prettier（含 index.html / app.html）
• Stylelint（CSS / SCSS / Less / Vue SFC）
• Husky + lint-staged + Commitlint
• VSCode 保存自动格式化

面向 Vue 3 / Vite 与 Nuxt 3+ 业务项目。

环境要求

• Node.js ≥ 20.19

安装

pnpm add -g web-code-lint
# 或
npm install -g web-code-lint

在项目中初始化

# 新项目（默认）：强类型，any 为 error
npx web-code-lint@latest init
npx web-code-lint@latest init --nuxt

# 存量项目：清理旧配置、强制升级核心依赖，any 仅 warn
npx web-code-lint@latest init --legacy
npx web-code-lint@latest init --nuxt --legacy

| 选项 | 说明 | | -------- | --------------------------------------------------------------------- | | --legacy | 存量项目 TS 兼容模式：any 仅 warn；并放宽部分 TS 规则。默认 strict 下 any 为 error | | --nuxt | 忽略 .nuxt / .output / .data 等生成与缓存目录、声明 Nuxt 全局变量、放宽 pages 单词组件名 | | --vue | 强制 Vue/Vite 预设（覆盖自动检测） | | --with-scss | 强制安装 SCSS 解析相关包（未扫描到 .scss 时） | | --with-less | 强制安装 Less 解析相关包 | | --no-git | 不安装 husky / lint-staged / commitlint | | --with-git | 无 .git 时也安装 Git 钩子相关包 |

若 package.json 含 nuxt 且未传 --vue，自动使用 Nuxt 预设。

TS 规则双模式

由 eslint.config.mjs 中 webCodeLintOptions.tsMode 控制（init 时写入）：

| 模式 | 命令 | no-explicit-any | 适用 | | ---- | ---- | ----------------- | ---- | | strict（默认） | init | error | 新项目、强类型 | | legacy | init --legacy | warn | 存量项目渐进接入 |

legacy 只将 no-explicit-any 降为 warn；未使用变量、CommonJS require()、单词组件名及其他规则均与默认 strict 模式保持一致。后续可在 eslint.config.mjs 将 tsMode 改回 strict。

init --legacy 会在生成新模板前直接删除冲突的 .eslintrc*、.eslintignore、.stylelintrc*、.prettierrc* 和旧 Commitlint 配置，并清理 package.json 中对应的旧配置字段及已知不兼容规则包。eslint.config.mjs、stylelint.config.cjs、prettier.config.cjs 等当前模板目标始终整文件覆盖。

HTML 与模板

| 文件 | ESLint | Prettier | Stylelint | | --------------------------- | ------------------ | --------------------------------- | ---------------- | | .vue 的 <template> | vue/html-* 等模板规则 | Prettier 3 内置 vue 解析器排版 | <style> 语法校验 | | .vue 的 <script> / <style> | TS / Vue 语义规则 | Prettier 3 内置 vue 解析器排版 | <style> 语法校验 | | 根目录 index.html、app.html | 不校验 | lint / lint:fix 会格式化 | — |

业务 UI 规范集中在 Vue SFC 模板；入口 HTML 仅做排版。

v-html 使用 vue/no-v-html: warn（XSS 风险提示，编辑器黄色警告）；若团队要求禁止，可在 eslint.config.mjs 改回 error。

Nuxt 说明

• init --nuxt 会写入 tsconfig.eslint.json（覆盖 app/、constants/ 等），.ts 与 .vue 分轨解析
• 已忽略 Nuxt 生成与缓存目录：.nuxt/、.output/、.data/、.nitro/、.cache/，以及 .vercel/、.netlify/ 等部署产物（build/ 若含 Vite 等源码需保留 lint，勿整体忽略）
• init 不再为了压制 deprecated 提示而改写业务项目的传递依赖 overrides；这类次要警告仅提示，不阻断安装
• 已声明常用 Nuxt 自动导入 API
• 若已用 [@nuxt/eslint](https://nuxt.com/docs/guide/concepts/code-style#eslint)，注意避免与团队规则重复叠加

Vue / Vite（src/ 目录）说明

• 勿对 Vite 项目使用 --nuxt；标准 Vue 脚手架用 init 或 init --vue
• init 会写入 tsconfig.eslint.json（extends tsconfig.app.json，include 含 src/**、types/** 等），避免 src/api/*.ts 等 Parsing error 刷屏
• typescript-eslint v8 禁止 allowDefaultProject 使用 ** 宽 glob，业务代码须纳入 tsconfig.eslint.json，不能靠白名单兜底

常用命令

• npm run lint / npm run lint:fix：由 scripts/run-lint.mjs 串联 ESLint → Stylelint → Prettier（check）；仅 error 导致失败（warn 与 pre-commit 行为一致）；fix 在 Prettier 后再跑一轮 ESLint --fix；eslint.config.mjs 末尾使用 eslint-config-prettier/flat 关闭与 Prettier 冲突的格式规则
• 全部通过时显示「代码规范检查 · 100%」汇总（不再逐项列出 ESLint / Prettier / Stylelint）
• lint:fix 修复阶段静默执行，仅在最后输出一次完整校验结果（与 lint 一致，不重复打印）

编辑器与 CLI 分工

| 场景 | 行为 | | ---- | ---- | | 保存任意源码 | Prettier 按 prettier.config.cjs 排版，并执行 ESLint / Stylelint 可自动修复规则 | | .vue | 同上；eslint-config-prettier/flat 在配置末尾关闭与 Prettier 冲突的格式规则 | | npm run lint:fix | ESLint → Stylelint → Prettier（与 lint 同一顺序；Prettier 最后统一排版） | | Git commit | lint-staged 对暂存文件执行 fix 链；默认 --no-stash 跳过 stash 备份以提速（见 ensure-git-hooks.mjs 注释，可自行改回） | | warn vs error | npm run lint、lint:fix、pre-commit 行为一致：仅 error 失败；warn（如 v-html、legacy 下的 any）编辑器黄色提示，不阻断 lint / commit。CI 若要将 warning 视为失败，可自行在流水线加 eslint . --max-warnings 0 |

初始化会生成 .vscode/settings.json 和 .vscode/extensions.json。请使用项目根目录打开 VS Code / Cursor，安装推荐的 Prettier、ESLint、Stylelint、Volar 扩展，并在首次初始化后执行一次 Reload Window。模板对 Vue、JS、TS、CSS、Less、HTML、JSON、Markdown 等语言分别显式开启 formatOnSave，并配置 source.fixAll.prettier 保存动作作为兼容兜底，避免被用户级语言设置覆盖。

Monorepo 子包

scripts/ensure-git-hooks.mjs 在 prepare 时将 core.hooksPath 指向子包内 .husky，使父仓库根目录的 Git 也能执行子包钩子。

优点与注意

优点

• 开箱即用：一条 init 覆盖 ESLint / Prettier / Stylelint / Git 钩子与 VSCode 推荐配置，降低团队接入成本。
• 栈选型主流：ESLint 9 flat config、eslint-plugin-vue v10、typescript-eslint v8、Stylelint 17，与当前 Vue / Nuxt 生态一致。
• 职责清晰：ESLint 管语义、Prettier 管排版（不依赖 eslint-plugin-prettier）；eslint-config-prettier/flat 关闭冲突规则；.vue 的 <style> 语法走 Stylelint
• Nuxt 友好：生成目录忽略、全局变量、pages/ 单词组件名等按预设区分，减少误报。
• 可维护：规则集中在模板 eslint.config.mjs，业务项目通过 webCodeLintOptions.preset / tsMode 切换，无需 fork 整套配置。

注意

• 范围偏 Vue 全家桶：独立维护的大量 .html 页面、邮件模板等不在默认 ESLint 语义校验内，需团队自行扩展。
• 规则偏严：默认 strict 下 no-explicit-any 等为 error；存量项目可用 init --legacy（any 仅 warn）。v-html 默认 warn（不拦 lint / commit）。老项目首次接入仍可能改动面大，宜配合 lint:fix 与分批启用。
• 与 @nuxt/eslint 并存时需约定：避免同一类规则重复配置；本套件侧重 Stylelint + Prettier + 团队 Vue/TS 约定。
• CLI 能力单一：目前仅 init，后续版本若需 doctor、规则 diff、升级向导等需另行扩展。
• 重复 init 会覆盖模板：eslint.config.mjs、run-lint.mjs、.vscode/settings.json 等会被整文件替换，手改内容请先备份或 fork 规则。
• 老项目接入：首次 lint:fix 可能改动大量文件，建议在独立分支执行并 code review。

依赖安装策略

init 不会无脑装满列表，而是：

1. 按项目扫描：未发现 .scss / .sass、.vue 内未使用 lang="scss"、且未声明 sass 依赖时，跳过 SCSS 解析相关包；Less 同理。
2. 按 Git 状态：无 .git 时不装 husky、lint-staged、commitlint，也不写入 prepare / lint-staged（git init 后重新 init 即可）。使用 --no-git 重跑 init 会移除 lint-staged，并从 prepare 中剥离 husky / ensure-git-hooks（保留脚手架原有的其他 prepare 脚本）。
3. 去重与强制升级：package.json 里已有且版本满足要求的包不再重复安装；版本过旧（如 ESLint 8、eslint-config-prettier 8 不支持 /flat）会先强制重写为工具要求的版本范围，再调用包管理器安装。npm 老项目使用 --force 绕过残留 peer 冲突。
4. 版本锁定：核心 ESLint / Prettier / TypeScript 等依赖带 ^ 范围（如 eslint@^9.39.0），减少不同时间 init 时装到不兼容主版本的概率。

deprecated、可选依赖缺失、Node 推荐版本等次要信息只以 warning 输出；网络失败、私库认证失败或包管理器真正返回非零状态仍会阻断并给出重试提示。

含私有包的老项目

在执行 init --legacy 前，项目必须已通过 .npmrc 或 CI 环境配置正确的私有 registry 和认证信息。工具会沿用包管理器配置，不会把账号、密码或 token 写进项目；若 pnpm 的锁文件供应链校验出现私有包 404，会额外提示检查 registry。不要将认证凭据提交到 Git。

典型纯 Vue + CSS 小项目可比「全量安装」少 4～7 个 直接依赖；尚未 git init 的目录还会再少 4 个 Git 相关包。计划使用 SCSS/Less 但仓库里还没有对应文件时，可加 --with-scss / --with-less。

License

MIT