直接替换老项目CSS框架90%导致布局错乱，因存在HTML硬编码类名、JS DOM查找及服务端模板依赖；须先扫描真实页面识别有效类名，再分层加载CSS并桥接JS类名，最后按容器边界切片迁移。
直接替换老项目的 CSS 框架，90% 会导致线上页面布局错乱、交互失效、JS 逻辑断裂——这不是操作太急，而是旧项目里散落着大量隐性依赖：HTML 中硬编码的类名、JS 里用 document.querySelector('.col-md-6') 做 DOM 查找、甚至服务端模板拼接的 class 字符串。
先确认哪些类名真正在用，而不是“看起来在用”
老项目常有大量“死类名”：被注释掉的、只在某次 A/B 测试中临时加的、或早被 JS 动态移除但 CSS 还留着。盲目替换，等于拿锤子敲没坏的零件。
- 用
PurifyCSS或unused-css扫描真实 HTML 页面（不是开发环境 mock），输出当前实际生效的类名列表 - 重点筛出高频出现的类：如
.btn、.modal、.col-开头的网格类、.is-active这类状态类 - 对每个候选类，执行
grep -r "\.btn" src/ --include="*.html" --include="*.js" --include="*.ts"，看它是否出现在 JS 的classList.toggle、querySelector或埋点字段中
新框架 CSS 必须后加载，且用 @layer 显式分层
浏览器按 <link> 加载顺序解析样式，但框架自带高权重选择器（如 .ant-btn-primary 或 html body .tw-text-lg），如果你的新 CSS 在旧框架之后加载，却没控制好层叠逻辑，结果就是样式部分覆盖、部分失效。
- 所有旧框架的
<link>必须放在<head>最顶部；新框架 CSS 放在它们之后、自定义样式之前 - 在新 CSS 入口文件开头声明：
@layer legacy, components, utilities;，然后把旧样式规则包裹进@layer legacy { ... }，新组件样式写进@layer components { ... } - 避免用
@import在主样式里引入新框架——它会破坏@layer顺序，改用构建工具显式import或<link>
JS 里不能硬依赖旧类名，得加一层兼容桥接
一旦你删掉 .modal-open，而某个 jQuery 插件还在靠它控制 <body> 滚动锁定，页面就会卡死。别指望 JS 重写一遍，先兜住。
立即学习“前端免费学习笔记（深入）”；
- 对关键类名（如
.show、.active、.disabled），在 JS 中改用属性选择器过渡：document.querySelector('[class~="show"]')或el.classList.contains('show') || el.classList.contains('tw-block') - 在入口 JS 中注入轻量桥接逻辑：监听 DOM 变化，当检测到旧类名被添加时，自动同步添加对应的新类名（如
.is-open → .modal-open） - 禁止在新组件中复用旧类名语义：不要让
.btn--primary同时承担 Bootstrap 的.btn-primary和 Tailwind 的bg-blue-600行为——职责必须收敛
迁移不是全量切换，而是按“容器边界”切片上线
最安全的路径不是“换掉 Bootstrap”，而是“让设置页完全脱离 Bootstrap”。老项目 DOM 结构往往不干净，强行全局替换等于放弃可控性。
- 选一个低流量、高内聚、无第三方插件依赖的页面（比如「个人设置」或「帮助中心」），用新框架从头重写，保留旧路由和 API，只换样式和结构
- 用
<div class="legacy-page">...</div>包裹老页面区域，在其 CSS 中加.legacy-page { all: unset; }（慎用，仅限强污染场景），再局部重置基础样式 - CI 中加入
stylelint规则：禁止新代码中出现旧框架类名（如no-unknown-classes配合白名单）
真正卡住进度的，从来不是新框架学不会，而是那个写在 jQuery 插件回调里的 $(this).closest('.panel').find('.title') ——它不报错，但一换框架就找不到元素。动手前，先花半天跑一遍 grep 和 PurifyCSS，比写十行新 CSS 更重要。
