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 → 导致双遮罩、<code>z-index 冲突、iOS 滚动卡顿
• 把 <div class="offcanvas"> 嵌套在 <code><main></main> 或 <div class="container"> 内 → 遮罩不显示、动画卡半截 <li>用 <code>data-toggle="offcanvas"（旧写法）或拼错 data-bs-target → 触发无效，控制台报 Cannot read properties of null

正确做法：把 <div class="offcanvas offcanvas-start" id="sidebar"> 放在 <code> 直接子级，与 <nav></nav>、<main></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 内联样式。


VPS Bootstrap
从零启动全新 VPS，完成 OpenClaw 完整部署，包括备份/恢复及恢复后验证。用于 OpenClaw 部署。
下载

常见误区：

• 给 .offcanvas-backdrop 加 backdrop-filter: blur(8px) → 无效，因为背后是纯色层，没内容可模糊
• 给 body 直接加 backdrop-filter → 整个页面都糊了，包括弹出的菜单
• 用 opacity 调整遮罩透明度 → 点击区域仍完整，用户易误判是否可点

正确做法：

• 改遮罩深浅：.offcanvas-backdrop { background-color: rgba(0, 0, 0, 0.3) !important; }
• 实现模糊遮罩：在 底部加 <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 背景是纯色或未设置，那再好的滤镜也看不出效果。