必须遍历真实文本节点才能准确定位偏移量，因html中视觉连续文本常被拆分为多个text节点，直接用textcontent索引会导致offset错误；安全创建range需确保目标元素已渲染、含text节点、起点终点属同一祖先，surroundcontents仅支持单个text节点内范围。
不能靠 textContent 索引直接算偏移量，必须遍历真实文本节点才能准确定位——这是最常踩的坑。
为什么 setStart/setEnd 的 offset 容易错？
因为 setStart(node, offset) 中的 offset 是相对于 node 自身内容的字符数，而 HTML 结构里一个“视觉上连续”的文本，往往被拆成多个 Text 节点（比如中间插了 <strong></strong>、换行、空格节点）。直接对整个容器调 textContent 取索引，会跳过这些分隔点，导致 offset 偏大或落在非法位置。
- 常见错误：用
el.textContent.indexOf("foo")得到 12，就写range.setStart(el.firstChild, 12)→ 报错或选错位置 - 正确做法：用
TreeWalker或递归遍历所有Node.TEXT_NODE，累计真实字符长度，边走边匹配 -
offset必须 ≥ 0 且 ≤node.textContent.length，超出就抛IndexSizeError
如何在 contenteditable 区域里安全创建 Range？
先确保目标元素已渲染、非空、且包含文本节点；否则 createRange() 创建后调 setStart() 会失败。
- 别在
DOMContentLoaded前操作，尤其在线运行器中 HTML 和 JS 分栏时 DOM 更慢 - 检查
node.nodeType === Node.TEXT_NODE再传给setStart()，避免把Element当文本节点用 - 起点和终点必须属于同一祖先元素（common ancestor），跨
<p></p>和<div> 直接设 range 会触发 <code>InvalidStateError - 推荐用
range.selectNodeContents(el)先兜底，再用setStart/setEnd微调，比从零构建更稳 - 典型报错：
InvalidStateError: The range is not collapsed and does not select a single node - 替代方案更实用：
range.extractContents()拿出片段 → 创建document.createElement('mark')→mark.appendChild(extracted)→range.insertNode(mark) - 如果不想删原内容，改用
range.cloneContents()+range.deleteContents()+range.insertNode()组合 - 注意：
extractContents()后原 DOM 节点消失，要提前存引用或重绘逻辑
surroundContents() 为什么总报 InvalidStateError？
它只接受完全落在**单个文本节点内**的 range，哪怕多一个空格节点、跨一个 <br> 或起点终点不在同一 Text 节点，都失败。
真正难的不是写几行 createRange()，而是判断“这段文字到底落在哪个文本节点里、偏移多少”——这需要你亲手遍历节点树，而不是靠字符串搜索偷懒。
