offcanvas 是 Bootstrap 5 实现侧边展开遮罩菜单的唯一标准方案，必须置于 body 直接子级、避免嵌套、正确配置 data-bs-toggle 和 data-bs-target，并区分桌面常驻与移动端抽屉两套 DOM 结构。
offcanvas 是唯一可靠路径，别手写遮罩层
Bootstrap 5 官方不提供“侧边展开遮罩菜单”这种独立组件，offcanvas 就是为此设计的标准方案——它天然包含 transform 推入、背景遮罩（.offcanvas-backdrop）、ESC 关闭、点击遮罩收起等全部行为。手写 position: fixed + display 切换，等于自己实现一整套交互逻辑，90% 的失败都源于绕开 offcanvas。
常见错误包括：
- 手动添加
<div class="modal-backdrop">或自定义遮罩 div → 导致双遮罩、z-index冲突、iOS 滚动卡顿 - 把
<div class="offcanvas">嵌套在<main>或<div class="container">内 → 遮罩不显示、动画卡半截 - 用
data-toggle="offcanvas"（旧写法）或拼错data-bs-target→ 触发无效，控制台报Cannot read properties of null
正确做法：把 <div class="offcanvas offcanvas-start" id="sidebar"> 放在 <body> 直接子级，与 <nav>、<main> 同级；触发按钮必须带 data-bs-toggle="offcanvas" 和匹配的 data-bs-target="#sidebar"。
桌面常驻 + 移动端侧滑，必须拆两套 DOM 结构
想让侧边栏在桌面显示为常驻导航、移动端才收进侧边栏，不能靠 JS 动态切换 show 状态或增删类——那样会破坏 offcanvas 生命周期，导致遮罩残留、重复初始化或关闭失效。
正确结构是两套独立 DOM：
- 桌面导航：
<nav class="d-none d-lg-block">...</nav>（用position: sticky或position: fixed锚定，避免和栅格混用） - 移动端抽屉：
<div class="offcanvas offcanvas-start d-lg-none" id="mobile-sidebar">...</div> - 触发按钮需分别指向不同 ID，不能共用
data-bs-target
切勿给同一个元素同时加 col-md-3 和 offcanvas 类——col 强制参与 flex 布局，而 offcanvas 依赖 position: fixed 脱离文档流，两者冲突必然出问题。
自定义遮罩颜色和模糊效果，作用对象必须精准
.offcanvas-backdrop 和 .offcanvas 是两个独立元素，CSS 作用域隔离明显。直接改 .offcanvas 背景有效，但改遮罩色必须针对 .offcanvas-backdrop，且需 !important 覆盖 Bootstrap 内联样式。
常见误区：
- 给
.offcanvas-backdrop加backdrop-filter: blur(8px)→ 无效，因为背后是纯色层，没内容可模糊 - 给
body直接加backdrop-filter→ 整个页面都糊了，包括弹出的菜单 - 用
opacity调整遮罩透明度 → 点击区域仍完整，用户易误判是否可点
正确做法：
- 改遮罩深浅：
.offcanvas-backdrop { background-color: rgba(0, 0, 0, 0.3) !important; } - 实现模糊遮罩：在
<body>底部加<div id="offcanvas-blur-overlay" class="d-none"></div>，再用 CSS 控制其显隐和滤镜，z-index设为1045（低于遮罩层1050，高于页面内容） - 确保该 overlay 不被任何父容器的
overflow: hidden截断，且用display: block/none控制显隐（Safari 下visibility或opacity不触发重绘）
移动端滚动穿透和 Safari 兼容性，根源在合成层与 overflow 处理
开启模糊遮罩后，iOS Safari 常出现滚动卡顿、点击失效或白屏，不是代码写错了，而是合成层冲突和 overflow 处理不当。
关键点：
- 别在
show.bs.offcanvas事件里手动设document.body.style.overflow = 'hidden'——offcanvas已自动处理，重复设置会冲突 -
.offcanvas-body必须设max-height和overflow-y: auto，否则内容撑高遮罩，导致灰色区域远超视口，滚动时遮罩“跟着动” - Safari 下
backdrop-filter必须写双前缀：backdrop-filter: blur(10px); -webkit-backdrop-filter: blur(10px); - 若用了
position: sticky锚定桌面侧边栏，要确认其父容器（如.row）没设overflow: hidden或transform（offcanvas、navbar-sticky-top都会触发）
最易被忽略的是：模糊遮罩的生效前提是背后有真实可模糊的内容——如果 body 或 main 背景是纯色或未设置，那再好的滤镜也看不出效果。
