必须用--bs-offcanvas-width变量控制宽度，禁用width/max-width；该变量须设在body直接子级的.offcanvas元素上，外部样式需加在该元素自身，否则动画、遮罩、ESC关闭均失效。
必须用 --bs-offcanvas-width，别碰 width 或 max-width
Bootstrap 5 的 offcanvas 动画、遮罩定位、滚动锁逻辑全依赖 --bs-offcanvas-width 这个 CSS 自定义属性。硬写 width: 280px 或 max-width: 300px 看似生效，实则会破坏 transform 基线计算——Safari 下滑入抖动、遮罩只盖半屏、ESC 关闭失效都是典型表现。
正确做法只有两种：
<div class="offcanvas offcanvas-start" style="--bs-offcanvas-width: 280px;">- 外部样式：
.offcanvas-sidebar { --bs-offcanvas-width: 280px; }，且该类必须加在<div class="offcanvas">元素自身上
--bs-offcanvas-width 必须设在 <div class="offcanvas"> 自身，且是 <body> 直接子级
很多人把 offcanvas 套在 <main>、<div class="container"> 或自定义 wrapper 里，再给外层加变量——JS 初始化时根本读不到，document.getElementById() 返回 null，控制台报 Cannot read properties of null 就是这个原因。
必须确保：
立即学习“前端免费学习笔记（深入）”；
-
<div class="offcanvas">是<body>的直接子节点（不能嵌套） - 变量写在该节点上，不是父容器、不是 wrapper、不是
class="sidebar"这类自定义类 - 同时加
offcanvas-start和offcanvas-end会导致变量被忽略
图标模式（窄宽度）下必须重置 padding 和居中逻辑
当把 --bs-offcanvas-width 压到 80px 这类图标模式时，原生的 list-group-item 或 nav-link 样式完全不适用：默认 padding: 0.5rem 1rem 和 line-height: 1.6 会让小图标上下空隙过大、点击区域偏小、视觉松散。
需手动覆盖：
- 用
d-flex align-items-center justify-content-center替代line-height居中，更稳定 - 显式写
padding: 0.75rem 0，去掉左右内边距 - Font Awesome 图标务必加
fa-fw类，防宽度不一导致列表晃动 - 统一用
fs-4或font-size: 1.25rem控大小，别混用text-lg或h5
关闭按钮失效？检查 data-bs-dismiss="offcanvas" 是否在正确位置
很多开发者以为放个 <button aria-label="Close"></button> 就能关 offcanvas，结果点了没反应——关闭行为完全依赖 data-bs-dismiss="offcanvas" 这个触发器，JS 内部靠它识别并销毁实例。
该属性必须写在按钮上，且按钮需位于 offcanvas 内部（不能放在外部再 JS 绑定 click）。标准写法：
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
如果用了 Vue/React，没用 Teleport 或 createPortal 挂到 document.body，也会导致 backdrop 插入错位、滚动锁不释放。
