Offcanvas 必须为 body 直接子元素，否则遮罩不显示、动画卡顿；桌面与移动端需分设两套 DOM 结构，禁用 JS 切换类或混用栅格；自定义遮罩需正确选择器，禁用遮罩应使用 data-bs-backdrop="false"。
offcanvas 必须是 body 直接子元素，否则遮罩不显示、动画卡顿
Bootstrap 5 的 offcanvas 依赖 DOM 位置触发 backdrop 插入和事件绑定。如果把它嵌套在 <div class="container">、<main> 或任何带 overflow: hidden / transform 的父容器里，遮罩层（.offcanvas-backdrop）可能根本不会渲染，或者点击无响应。
- 正确写法：把
<div class="offcanvas offcanvas-start" id="sidebar">放在<body>开头或结尾，与<nav>、<main>同级 - 错误写法：用 JS 动态
appendChild到某个 div，或包裹在.row/.col里 —— 这会导致getInstance找不到实例，data-bs-dismiss失效 - 验证方式：打开 DevTools，搜索
.offcanvas-backdrop元素是否存在；若不存在，大概率是结构问题
桌面常驻 + 移动端侧滑，必须拆两套 DOM，不能靠 JS 切换类
想让菜单在桌面显示为固定侧边栏、移动端才收进侧滑抽屉，别用 JS 控制 show 或增删 offcanvas 类 —— 这会破坏生命周期，导致 backdrop 残留、关闭失效、滚动锁死。
- 桌面导航：用
<nav class="d-none d-lg-block">+position: sticky或fixed锚定，不依赖offcanvas - 移动端抽屉：单独一个
<div class="offcanvas offcanvas-start d-lg-none" id="mobile-sidebar">，仅在lg断点以下生效 - 触发按钮要分开：桌面用常规链接，移动端用带
data-bs-toggle="offcanvas"和data-bs-target="#mobile-sidebar"的按钮 - 千万别给同一个元素同时加
col-md-3和offcanvas—— 栅格布局与position: fixed冲突，行为不可预测
自定义遮罩颜色或模糊效果，必须作用于正确选择器
.offcanvas-backdrop 是纯色层，直接加 backdrop-filter 没用；而模糊主页面内容，又不能直接模糊整个 body（否则菜单也糊了）。关键在于层级控制和作用对象。
- 改遮罩透明度：覆盖
.offcanvas-backdrop { background-color: rgba(0, 0, 0, 0.3) !important; }，别用opacity - 实现模糊背景：在
<body>底部加<div id="offcanvas-blur-overlay" class="d-none"></div>，CSS 写.offcanvas.show ~ #offcanvas-blur-overlay { display: block; backdrop-filter: blur(10px); z-index: 1045; } - 注意 Safari：必须加
-webkit-backdrop-filter，且#offcanvas-blur-overlay不能被任何父容器的overflow: hidden截断 - 禁用遮罩？用
data-bs-backdrop="false"，而不是手动删掉.offcanvas-backdrop类 —— 后者会让 JS 逻辑异常
移动端滚动穿透和 Safari 白屏，往往源于重复锁 body
offcanvas 自动处理 body 滚动锁定（overflow: hidden），但如果你在 show.bs.offcanvas 事件里又手动设 document.body.style.overflow = 'hidden'，就会冲突，导致 iOS Safari 卡顿、点击失效甚至白屏。
- 检查 JS 是否有重复设置
overflow的逻辑 —— 删除它，完全信任 Bootstrap 的内置行为 -
.offcanvas-body必须设max-height: calc(100vh - 56px)和overflow-y: auto，否则长菜单会撑高遮罩，造成灰色区域远超视口 - iOS 双指缩放时意外横向滚动？确认隐藏的桌面侧边栏没用
d-none而是彻底移出 DOM（用d-lg-none配合两套结构），否则仍参与 layout flow - 屏幕阅读器持续朗读？确保移动端
offcanvas的aria-hidden="true"在关闭时被正确还原 —— 不要手动操作，靠 Bootstrap 自动管理
真正麻烦的不是写样式，而是让两套结构（桌面常驻 + 移动端 offcanvas）在 DOM 层级、可访问性、滚动行为上互不干扰。稍一混用栅格或 JS 控制，就容易在 Safari 或辅助技术下崩掉。
