不能批量迁移。所有声称“一键转bem”的脚本或正则替换都会导致样式错乱、功能失效；必须先用grep定位每个.btn的真实语义，再逐处替换并保留旧类加注释，css用@layer分层，js需重写所有硬编码调用点。
不能批量迁移。所有声称“一键转BEM”的脚本或正则替换，都会在第三行代码就让按钮变宽、表单校验失效、埋点上报中断。
为什么 grep 比 sed 更关键
旧项目里一个 .btn 可能同时出现在：document.querySelector('.btn')、el.classList.contains('btn')、data-class="btn"、className.includes('btn')、EJS 模板的 <button class="btn <%= type %>"></button>，甚至 CSS 里的 .modal .btn。直接 sed -i 's/\.btn/.button__base/g' 会漏掉所有非标准用法，且无法判断哪个 .btn 实际对应 search-button 还是 delete-button。
必须先运行：
grep -r "\.btn" src/ --include="*.html" --include="*.js" --include="*.css" --include="*.ejs" --include="*.vue"
确认每个命中项的真实语义和上下文，再决定它该归属哪个 Block。
- 匹配到
document.querySelector('.btn')→ 说明 JS 强依赖该类名，必须保留或过渡 - 匹配到
<div class="btn"> 但旁边有 <code><div class="card"> → 很可能该按钮属于 card 场景，应归为 <code>card__button - 匹配到
.header .btn→ 说明它不是独立 Block，而是 header 的一部分，优先考虑header__cta
HTML 中只加不删，用注释锚定旧类
不要删除旧类名，否则 JS 绑定立刻断开。正确做法是在原有 class 属性中追加新 BEM 类，并把旧类用注释标出：
<button class="btn /* legacy */ button__base button--primary">提交</button>
这样既保证现有逻辑照常运行，又为后续清理提供明确标记。注意：注释必须写在引号内，且前后有空格，避免被某些构建工具误删。
- 服务端模板（如 Thymeleaf）也要同步加注释：
class="btn /* legacy */ user-card__action" - 禁止写成
class="btn button__base /* legacy */"—— 注释位置错位会导致部分解析器丢弃整个 class 值 - 若旧类名含空格（如
class="btn primary"），必须整体包裹注释：class="btn primary /* legacy */ button__base button--primary"
CSS 权重冲突时，@layer 是唯一可靠解
旧 CSS 里 #main .form .input:focus 的权重远高于新写的 .form-item__input:focus，强行覆盖要用 !important，但这等于给技术债打补丁。
现代方案是用 @layer 显式分层：
@layer legacy {
#main .form .input:focus { outline: 2px solid red; }
}
@layer bem {
.form-item__input:focus { outline: 2px solid var(--focus-color); }
}
浏览器按 layer 声明顺序覆盖，无需调整 <link> 顺序，也不依赖加载时机。
- 必须在所有旧 CSS 规则前声明
@layer legacy，否则规则不被识别为该层 - 若项目需兼容不支持
@layer的老浏览器（如 IE、旧版 Safari），退而求其次：确保 BEM 的<link>标签严格放在旧 CSS 之后，并在 BEM 文件开头加/*! @layer bem */注释作人工提示 - 禁用
.legacy-wrapper .form-item__input这类“命名空间包裹”方案——它引入新选择器层级，反而放大耦合风险
JS 兼容不能靠字符串包含，要定位真实调用点
document.querySelector('[class*="btn"]') 看似安全，实则危险：它会匹配到 submit-btn、btn-group 甚至 abandoned（含 btn 子串）。这不是过渡，是埋雷。
真正要做的，是逐个定位并重写所有硬编码类名的 JS 调用点：
-
el.classList.contains('btn')→ 改为el.matches('.button__base, .button__icon, .button__text')（列出所有合法 BEM 类） -
document.querySelectorAll('.nav-item')→ 先确认这些元素是否都属于同一 Block（如main-nav），再改为document.querySelectorAll('.main-nav__item') - 所有
data-*属性引用（如data-trigger="btn"）必须同步更新为data-trigger="button__base"，否则交互链路断裂 - Vue / React 中的
className.includes('btn')必须替换为className.split(' ').some(c => c.startsWith('button__'))，避免误判
BEM 迁移最难的从来不是改名，而是把散落在 HTML、JS、模板、埋点配置里的隐式依赖显性化——一旦漏掉一个 data-class="btn"，上线后那个按钮就再也不会触发点击事件了。
