Bootstrap 5 offcanvas 默认自带遮罩，无需手动添加 backdrop 元素；错误手写会导致双遮罩、z-index 冲突及 iOS 卡顿；应通过覆盖 .offcanvas-backdrop 的 background-color 或 CSS 变量调整透明度，避免使用 opacity；响应式场景需用 d-lg-block/d-lg-none 分离两套 DOM 结构，而非 JS 切换；设为 transparent 后需校准 backdrop、滚动和关闭行为。
Offcanvas 默认就有遮罩，别自己手写 backdrop
bootstrap 5 的 offcanvas 组件原生支持半透明遮罩，不需要额外写 .backdrop div 或 js 控制显隐。只要结构正确，data-bs-backdrop="true"（默认值）就会自动插入并渲染 .offcanvas-backdrop 元素，背景是 rgba(0,0,0,0.5)。
常见错误是手动加一个 div 并设 position: fixed; background: rgba(0,0,0,0.5)——这会导致双遮罩、z-index 冲突、点击失效，甚至 iOS 滚动卡顿。
- 确保触发按钮有
data-bs-toggle="offcanvas"和对应href或data-bs-target -
offcanvas容器必须带data-bs-placement（如"start"） - 不要移除或重命名
.offcanvas-backdrop类——它是 Bootstrap JS 动态管理的
想改遮罩透明度？直接覆盖 CSS 变量或 background-color
默认遮罩太深或太浅，不建议用 opacity 调整整个 .offcanvas-backdrop 元素，那会影响点击穿透行为；应只改背景色透明度。
最稳妥的方式是覆盖其 background-color：
.offcanvas-backdrop {
background-color: rgba(0, 0, 0, 0.3) !important;
}
如果你用的是 Bootstrap 5.2+，也可以用 CSS 变量（需确认主题支持）：
:root {
--bs-offcanvas-backdrop-bg: rgba(0, 0, 0, 0.3);
}
- 避免用
opacity: 0.3——它会让遮罩“变薄”，但点击区域仍完整，用户易误判是否可点 - 若设为
rgba(0,0,0,0)，遮罩视觉消失，但逻辑仍在（body 滚动仍被锁），需同步加data-bs-backdrop="false" - 修改后记得清缓存，Bootstrap 的 CSS 权重高，普通选择器常被忽略
桌面端常驻 + 移动端侧滑：别用 JS 切类，用响应式工具类拆两套结构
想让侧边栏在桌面显示为常驻导航、移动端才收进 offcanvas，不能靠 JS 动态切换 show 状态或增删 offcanvas 类——那样会破坏 offcanvas 的生命周期管理，导致 backdrop 残留或重复初始化。
正确做法是声明两套 DOM 结构，用 Bootstrap 响应式类控制显隐：
- 桌面常驻版：普通
<div class="d-none d-lg-block">...</div>（比如.navbar-nav或自定义 sidebar） - 移动端 offcanvas 版：单独一个
<div class="offcanvas d-lg-none">...</div>，配独立触发按钮 - 两套内容可以复用同一份数据或组件，但 DOM 必须分离
这样既保住了 offcanvas 的 backdrop、esc 关闭、点击关闭等原生能力，又避免了 JS 状态同步错乱。
Offcanvas 设为透明后，遮罩和滚动行为要重新校准
把 .offcanvas 背景设成 transparent 后，视觉上容易让人以为“没弹出来”，其实 backdrop 和 body 锁定依然生效。这是最容易被忽略的交互陷阱。
- 如果侧边栏内容很长，需允许页面滚动：给 offcanvas 标签加
data-bs-scroll="true" - 如果不想点击遮罩关闭：加
data-bs-backdrop="false"（注意：此时需提供明确关闭按钮） - 如果同时设
data-bs-backdrop="false"和data-bs-scroll="true"，iOS Safari 可能出现滚动粘滞，建议加touch-action: manipulation到 body - 透明状态下，
.offcanvas-header和.offcanvas-body的白色背景必须一并清掉，否则顶部/中部仍有一块白
透明不是“隐形”，而是“视觉穿透”——背后的 backdrop、滚动锁定、键盘事件都还在运行，得一个个确认是否符合预期。
