局部滚动容器必须显式声明 overflow-y: auto 才能触发滚动上下文，否则 ::-webkit-scrollbar 不生效、IntersectionObserver 误判；需配合明确高度、避免 fixed 定位干扰，并注意浏览器兼容性差异。
局部滚动容器必须显式声明 overflow-y: auto
很多开发者以为只要内容溢出，div 就会自动出现滚动条——其实不会。overflow-y: auto（或 scroll）是触发滚动上下文的硬性前提。没它，::-webkit-scrollbar 一类样式根本不会被解析，IntersectionObserver 也可能误判可见区域。
常见错误现象：
- 写了
::-webkit-scrollbar却完全没反应 - 局部区域内容撑开父容器，但无法滚动，页面反而全局滚动
- 移动端 Safari 显示空白或卡顿，实际是滚动上下文未建立
实操建议：
- 确保目标容器是块级元素（
display: block或默认值），且有明确高度（如height: 300px或max-height: 400px） - 避免在
html或body上写overflow来“统一控制”，这会污染整个页面滚动行为 - 如果用 Bootstrap，优先在
.card-body这类已有语义的容器上加style="overflow-y: auto; max-height: 300px;"，而不是包裹额外div
::-webkit-scrollbar 必须成套声明且不可挂载在根元素上
单独写 ::-webkit-scrollbar { width: 8px; } 是无效的。这个伪元素只在完整规则链+正确作用域下才生效。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 每个启用自定义滚动条的容器，必须同时声明：
::-webkit-scrollbar、::-webkit-scrollbar-track、::-webkit-scrollbar-thumb - 宽度/高度必须显式设置：垂直滚动需
width，水平滚动需height；值太小（如width: 2px）会被浏览器忽略 - 不要写在
html或body上——它只对当前元素的滚动容器起效；想全局控制？改用scrollbar-width+scrollbar-color（仅 Firefox 支持）
示例（安全写法）：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
.chat-log {
overflow-y: auto;
max-height: 400px;
}
.chat-log::-webkit-scrollbar {
width: 8px;
}
.chat-log::-webkit-scrollbar-track {
background: #f1f1f1;
}
.chat-log::-webkit-scrollbar-thumb {
background: #c1c1c1;
border-radius: 4px;
}Firefox 和 iOS/macOS 的滚动条支持差异极大
Firefox 完全无视所有 ::-webkit- 规则；iOS/macOS Safari 对 ::-webkit-scrollbar 的支持极弱，甚至不响应 :hover 状态。这不是 bug，是平台策略。
实操建议：
- Firefox 中，只用
scrollbar-width: thin和scrollbar-color: #666 #eee，且必须写在实际滚动容器上（如.list-container），不能写在* {} - macOS/Safari 16.4+ 才开始有限支持
scrollbar-color，但::-webkit-scrollbar-thumb:hover基本无效，别依赖交互反馈 - 若需跨平台一致外观，接受「滚动条颜色可调、粗细两级、无圆角无动效」的现实；强定制需求请用 JS 滚动库（如
simplebar）
固定定位元素（position: fixed）会破坏局部滚动上下文
当局部滚动区域内部或其祖先包含 position: fixed 元素时，它会脱离文档流，导致父容器无法正确计算高度，结果就是：滚动条存在但拖不动，或滚动范围远小于预期。
常见错误场景：
- 弹窗（
.modal）里嵌了一个.modal-body，但.modal-header设了fixed，整个 modal-body 失去滚动能力 - 侧边栏用
fixed，主内容区设了overflow-y: auto，但主区高度始终为 0
实操建议：
- 移除局部滚动区域内的
fixed元素；改用position: sticky（适合头部吸顶）或relative+top/transform定位 - 确保滚动容器的父级具备明确高度来源（比如
flex: 1、height: 100vh、或由子内容撑开） - 调试时临时加
border: 1px solid red到滚动容器，确认它的渲染尺寸是否符合预期
局部滚动不是加个 overflow 就完事；真正容易被忽略的是：滚动上下文是否真实建立、伪元素是否在正确作用域、以及不同浏览器对“滚动”这件事的理解根本不在同一套逻辑里。
