如何解决团队协作中HTML结构类名不统一的问题？

前端这块类名不统一确实很头疼，搞到最后样式互相冲突，维护成本翻倍。光靠文档约束基本没用，得上点硬手段。

首先推荐用 BEM 命名规范落地一套标准，比如统一写成 login__form-group、login__input 这种块-元素-修饰器结构，至少风格上能收敛。然后配合 stylelint 来做静态检查，它比 ESLint 更适合管 CSS/类名这类问题。

你可以配一个 stylelint 规则，用 selector-class-pattern 限制类名必须符合某种正则。比如只允许小写字母加中划线，并且必须以组件名开头：

{

  "rules": {

    "selector-class-pattern": "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$"

  }

}

再结合一个 HTML 检查工具比如 htmllint，可以用自定义规则检测 class 是否用了禁用词，像 container、wrapper 这种模糊词直接报错。

最后把这一套集成到 pre-commit 钩子里，用 husky + lint-staged，提交代码时自动跑一遍检查，不过就不能提交。这样新人也绕不开，久而久之就养成习惯了。

我们团队就这么干的，一开始骂声一片，两个月后大家都说真香。

这个问题根本原因是缺乏强制性的约束机制，光靠文档约定在多人协作中迟早会失控。我之前带团队也踩过这个坑，后来整了一套组合拳方案，现在分享给你。

首先明确一点：ESLint 是用来检查 JavaScript/JSX 的，对纯 HTML 文件支持有限，所以不能直接用 ESLint 检查类名。但我们可以通过其他方式实现类似的静态检查效果，核心思路是「规范 + 工具化 + 自动拦截」。

第一步，建立原子化的 CSS 命名规范，别再让人自由发挥。我们采用 BEM 的变种，但简化成三层结构：

组件名__元素名--状态

比如登录框就统一叫 login，输入框区域就是 login__field，激活状态是 login__field--focused。这种命名自带作用域，不容易冲突。

第二步，把常用布局结构抽离成基础语义类，用 CSS 自定义属性和原子类控制样式，而不是让每个人自己写容器类。比如在全局 CSS 里定义：

/* 基础布局类 */

.container { max-width: 1200px; margin: 0 auto; padding: 0 1rem; }

.wrapper { display: flex; flex-direction: column; min-height: 100vh; }



/* 表单相关原子类 */

.form-group { margin-bottom: 1rem; }

.field-box { position: relative; width: 100%; }

.input-style,

.text-input {

  width: 100%;

  padding: 0.5rem;

  border: 1px solid #ccc;

  border-radius: 4px;

}

注意这里虽然保留了多个类名，但它们是功能原子类，不是业务组件类。重点在于第三步：用工具强制校验。

第三步，使用 HTMLHint 做静态检查。它类似 ESLint 但专用于 HTML。安装：

npm install htmlhint --save-dev

然后在项目根目录加 .htmlhintrc 配置文件：

{

  "attr-name-style": "lowercase",

  "tagname-lowercase": true,

  "no-inline-style": true,

  "class-style": "lowercase",

  "id-class-value": "dash"

}

但这还不够细粒度。我们需要自定义规则来限制特定标签只能使用允许的类名。可以写一个简单的 AST 解析脚本，配合 htmlparser2 库：

// check-classes.js

const fs = require('fs');

const path = require('path');

const HTMLParser = require('node-html-parser');



// 定义白名单

const ALLOWED_CLASSES = new Set([

  'container', 'wrapper',

  'form-group', 'field-box',

  'input-style', 'text-input',

  'login__field', 'login__submit'

]);



const DISALLOWED_PATTERNS = [/^auth-/, /^wrapper$/, /^container$/];



function checkFile(filePath) {

  const content = fs.readFileSync(filePath, 'utf8');

  const root = HTMLParser.parse(content);

  const errors = [];



  function traverse(node) {

    if (node.classNames) {

      for (const cls of node.classNames) {

        // 检查是否在白名单

        if (!ALLOWED_CLASSES.has(cls)) {

          // 检查是否有禁用模式匹配

          if (DISALLOWED_PATTERNS.some(pattern => pattern.test(cls))) {

            errors.push(禁止使用类名: ${cls} in ${filePath});

          }

        }

      }

    }

    if (node.childNodes) {

      node.childNodes.forEach(traverse);

    }

  }



  traverse(root);

  return errors;

}



// 扫描 src 目录下所有 html 文件

const files = fs.readdirSync('src').filter(f => f.endsWith('.html'));

let hasError = false;



files.forEach(file => {

  const filePath = path.join('src', file);

  const errs = checkFile(filePath);

  if (errs.length > 0) {

    console.error(errs.join('n'));

    hasError = true;

  }

});



if (hasError) {

  process.exit(1);

}

然后在 package.json 里加个 npm script：

"scripts": {

  "lint:html": "node check-classes.js"

}

第四步，接入 git hook，确保不合规范的代码提交不了。用 husky + lint-staged：

npx husky install

npx husky add .husky/pre-commit "npx lint-staged"

配置 lint-staged：

"lint-staged": {

  "*.html": ["npm run lint:html"]

}

这样每次 commit 的时候就会自动检查 HTML 类名是否合规。

最后建议配合组件化开发。如果你们用 React/Vue 这类框架，干脆把公共结构封装成组件：

function LoginForm() {

  return (

    <div className="login__container">

      <div className="form-group">

        <input className="text-input" type="text" />

      </div>

    </div>

  );

}

通过组件调用而不是手写 HTML，从根本上减少不一致。

总结一下，单纯靠文档不行，必须做到三点：统一命名规范、工具自动检测、提交前拦截。这套流程跑顺了之后，新人入职给个模板+装好 pre-commit 就不会出问题。我们组现在连实习生都不会写错类名，就是因为改了代码不通过 pre-commit 根本 push 不上去，被逼的。