光靠“约定”拦不住重复 block 名，因微小差异难被肉眼识别且无运行时警告；需用机器可读的 json 索引表（如 blocks.json），配合 eslint/stylelint 校验、ci 扫描、vs code 插件及近义词检查，将重复从静默覆盖变为构建报错。
为什么光靠“约定”拦不住重复的 block 名
团队里没人故意撞名，但 user-card 和 user_profile、search-form 和 searchBox 这类微小差异，在 Git 提交、Code Review 甚至 PR 描述里都极难被肉眼识别。浏览器不报错，CSS 也不警告，直到某天 .user_profile__avatar 被 .user-card__avatar 的 margin 覆盖，而 DevTools 里两个规则并排显示，连谁先加载都得手动查 source order。
怎么建一份真正能用的全局 block 名索引表
索引表不是 Word 文档或 Confluence 页面——它必须是机器可读、可校验、能嵌入开发流的结构化数据。
- 用 JSON 文件维护，例如
blocks.json，内容为{"user-card": "用户信息卡片组件", "search-form": "全局搜索表单"} - 在 ESLint + stylelint 中接入
stylelint-selector-bem-pattern，并配置componentName: ["user-card", "search-form", ...]白名单 - CI 流水线中加一步脚本：用
grep -r '\.block-name' src/扫描所有 CSS/SCSS/JSX 中出现的类名，比对blocks.json，缺失项直接 fail 构建 - VS Code 安装 “BEM Helper” 插件，并指向该 JSON 文件，输入
user-时只提示已注册的user-card、user-list，不出现userProfile
block 名冲突最常发生在哪些环节
不是写代码时，而是改代码时。
- 重构旧页面，把
.header抽成独立组件，但已有另一个layout__header，开发者顺手起了page-header，结果和第三方 UI 库的page-header冲突 - 引入 npm 包（如
@company/ui），包内用了modal，而项目里早有popup，两者语义重叠却无关联，后续想统一风格时发现命名已锁死 - 设计师给新需求稿标注 “会员卡片”，前端起名
vip-card，后端接口字段却是memberCard，联调时 JS 里混用两种前缀，document.querySelector('.vip-card__name')始终返回 null
索引表要防的不是“重名”，是“同义不同名”
真正的坑不在 button 和 btn，而在 user-card 和 profile-card——它们指同一类 UI 单元，但被当成两个 block 分别实现、分别维护、分别加修饰符。久而久之，user-card--compact 和 profile-card--minimal 样式几乎一样，却无法复用。
- 索引表条目必须带业务语义注释，而非仅技术描述：“
user-card：用于个人中心、订单页、客服会话侧边栏等场景的用户基础信息展示，含头像、昵称、等级标识” - 新增 block 前，强制执行
jq '. | keys[]' blocks.json | grep -i "profile\|member\|user"，确认无近义词 - 允许 alias，但禁止实现：在
blocks.json里写"profile-card": {"aliasOf": "user-card", "deprecated": true}，工具链据此告警而非阻断
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
