offcanvas 必须是直接子元素，否则遮罩和动画失效；需避免与栅格混用、正确设置offcanvas-body滚动、图标对齐用d-flex align-items-center。
offcanvas 必须是
Bootstrap 5 的 offcanvas 组件依赖 DOM 结构稳定性：它会在初始化时自动将遮罩层（.offcanvas-backdrop）插入到 最末尾，并监听 body 级事件。如果把 <div class="offcanvas"> 嵌套在 <code><main></main>、<div class="container"> 或任何带 <code>overflow: hidden / transform 的父容器里，遮罩可能不显示、点击无响应，或菜单滑出一半卡住。
实操建议：
- 把
<div class="offcanvas offcanvas-start" id="sidebar"> 放在 <code>开头或结尾，与<nav></nav>、<main></main>同级 - 别用 JS 动态 append 到某个 div —— 这会导致
getInstance找不到实例，data-bs-dismiss失效 - 检查浏览器控制台是否报
Cannot read properties of null，大概率是document.getElementById('sidebar')返回 null，即 ID 不匹配或 DOM 未就绪 - 桌面常驻栏：
<aside class="col-lg-2 d-none d-lg-block">...</aside>，用position: sticky或position: fixed锚定 - 移动端抽屉：
<div class="offcanvas offcanvas-start d-lg-none" id="mobile-sidebar">...</div>，仅在 lg 以下生效 - 触发按钮需分别指向不同 ID，不能共用
data-bs-target - 给
<div class="offcanvas-body"> 加 <code>style="max-height: calc(100vh - 56px); overflow-y: auto;"（56px 是典型 navbar 高度，按实际调整） - 不要给外层
.offcanvas设height或max-height—— 它会破坏transform定位基线 - 若用了自定义 header，把它放进
<div class="offcanvas-header">，别塞进 <code>offcanvas-body，否则滚动区域包含 header，造成误触图标对齐要用
d-flex align-items-center，别信text-center或mx-auto在小屏下，
<i class="bi bi-house"></i> 文字很容易上下错位：图标偏上、文字下沉。这不是 margin 问题，而是字体基线（baseline）和行高（line-height）不一致导致的。强行加text-center或mx-auto只会让图标居中但文字仍漂移。稳解方案：
- 每个菜单项用
<a href="#" class="list-group-item list-group-item-action d-flex align-items-center"></a> - 图标放左边，加
me-2；文字用<span></span>包裹，避免换行干扰 - 如果是 SVG 图标，显式设
height="1.25rem" width="1.25rem"，否则缩放时比例失真 - 选中态直接用
activeclass，list-group-item-action已内置 hover/focus 样式
真实项目里最容易被忽略的，是 offcanvas 的 DOM 位置和响应式结构拆分 —— 不是写对 class 就完事，而是必须让两套逻辑（桌面常驻 + 移动抽屉）物理隔离，否则可访问性、键盘焦点、屏幕阅读器都会出硬伤。
- 每个菜单项用
offcanvas-start 类不能和 col 栅格混用，方向逻辑会被覆盖
很多人想“桌面用 col-3 固定展示，移动端用 offcanvas 抽屉”，于是给同一个元素同时加 col-md-3 d-none d-md-block offcanvas offcanvas-start —— 这会导致行为不可预测：col 类强制参与 flex 布局，而 offcanvas 依赖 position: fixed 脱离文档流，两者冲突。
正确做法是拆成两套独立结构：
.offcanvas-body 必须设 max-height 和 overflow-y: auto，否则内容撑高遮罩
默认情况下，offcanvas 高度随内容自适应，一旦菜单项超过视口高度，整个遮罩层也会被拉长，导致背景变灰区域远超屏幕范围，滚动时遮罩“跟着动”，体验断裂。
关键控制点：
