根本原因是CSS层叠上下文错乱导致z-index失效；需确保父容器设position:relative、建议列表用position:absolute+top:100%、z-index设在父容器上，并避免transform等触发新层叠上下文。
为什么搜索建议列表总被遮挡或消失
根本原因不是 JS 没触发，而是 z-index 失效或层叠上下文错乱。常见现象包括：建议列表卡在导航栏下面、被轮播图裁掉一半、点击后闪退、滚动时错位。这些问题 90% 都出在 CSS 层级控制上，和 JavaScript 逻辑无关。
- 父容器没设
position: relative，导致position: absolute的列表找不到锚点，飘到页面左上角 - 输入框所在区域有
overflow: hidden（比如卡片折叠区、轮播图 wrapper），直接把列表裁掉 - 某个祖先元素加了
transform、opacity: 0.99或will-change，意外创建了新层叠上下文，把建议列表锁死在局部层级里 -
z-index值设得再大也没用——因为父子不在同一个层叠上下文中，数值无法跨上下文比较
如何正确设置 z-index 和定位结构
必须同时满足三个条件：定位锚点 + 绝对定位 + 层级穿透。缺一不可。
- 包裹
<input>的容器（如<div class="search-box">）必须设 <code>position: relative，这是absolute定位的参照系 - 建议列表（如
<ul class="suggestions"></ul>）设position: absolute; top: 100%; left: 0; width: 100%，不用固定像素值，避免高度变化后脱节 -
z-index要设在「能影响列表显示顺序」的那层上：通常设在.search-box上（比如z-index: 100），而不是列表自身——否则一旦父级触发新层叠上下文，列表就出不来了 - 禁止给列表加
transform或will-change，这两者会创建独立层叠上下文，让z-index在内部失效 - 点击建议项后，立刻调用
inputElement.focus()并inputElement.setSelectionRange(inputElement.value.length, inputElement.value.length) - 必须手动清除正在等待的
debounceTimer（用clearTimeout），否则它会在 300ms 后仍执行一次过期请求 - 别依赖
blur事件隐藏列表——移动端点击建议后，input不一定触发blur；应在点击回调里直接设display: none或移除 class - 建议项用
<button></button>实现，而非<li>，确保焦点、悬停、可访问性一致，避免 Safari 移动端失焦闪退 - 接口路径必须是
/api/suggestions?q=xxx，q是必传 query 参数，后端做前缀匹配，不是全文检索 - 响应体必须是扁平 JSON 数组，例如：
["react", "react native", "react router"] - 禁止返回包装结构，如
{ data: [...], code: 200 }——除非你明确在 fetch 后统一解包，否则容易漏判data字段 - 前端解析时直接
response.json()然后.map(item => <li key="{item}">{item}</li>)，别多套一层res.data
移动端点击建议后列表闪退或光标错位
这不是 CSS 问题，是交互链断裂。用户点中建议词，输入框填入内容，但光标没落到末尾、键盘没弹起、防抖定时器还在跑——结果松手后又发一次旧请求，覆盖掉刚选中的词。
后端返回格式和前端解析的硬约束
接口设计不匹配，会导致建议列表空着不动，或者报 Cannot read property 'map' of undefined 这类错误。关键不是“能不能拿到数据”，而是“能不能直接用”。
立即学习“前端免费学习笔记（深入）”；
z-index 就完事”，而是“谁创建了上下文、谁被关在里面、谁有权决定它浮出来”。调试时打开 Chrome 的 Layers 面板，一眼就能看到哪些元素被框进独立上下文里——比猜 CSS 属性快得多。
