insertBefore 的目标节点必须是父容器的直接子元素；否则报错“refNode 不属于该父节点”。实操中需向上遍历定位块级容器，用 Range 精确定位，多媒体须包装为独立块级元素，并处理空行、Safari 时序等边界情况。
insertBefore 的目标节点必须是父容器的直接子元素
很多人卡在 insertBefore 报错 Failed to execute 'insertBefore' on 'Node': The node before which the new node is to be inserted is not a child of this node，本质是因为传入的 refNode 不属于调用该方法的父节点。在 HTML 编辑器中（比如基于 contenteditable 的富文本区域），光标位置对应的 DOM 节点常嵌套多层——你拿到的可能是 <span> 或 <em>，但它的父级可能不是编辑器根容器，而是中间某个 <p> 或 <div>。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 不要依赖光标直接所在的
Node作为refNode；先用getSelection().anchorNode获取位置，再向上遍历到最近的「块级可编辑容器」（如<p>、<div class="block">）作为父节点 -
refNode必须是这个父节点的childNodes中的一个；如果光标在文本末尾，anchorNode是文本节点，它可能没有兄弟节点可作参考，此时应 fallback 到parentNode.appendChild() - 用
Range更可靠：调用range.commonAncestorContainer找共同祖先，再用range.startContainer+range.startOffset定位插入点
插入多媒体节点前需标准化为独立块级元素
直接插入 <img> 或 <video> 到行内上下文（如 <span> 内部）会导致布局错乱、无法居中、编辑器选区异常等问题。多数现代编辑器（如 Slate、TipTap）都要求媒体节点独占一行或包裹在语义块中。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 始终将多媒体包装进一个
<figure>或带特定 class 的<div contenteditable="false">，例如：<div class="media-embed" contenteditable="false"> <img src="..." alt="..."> </div>
- 插入前检查
refNode的父节点是否为行内元素（display: inline），若是，应先将其提升到最近的块容器（如<p>），再执行insertBefore - 避免插入后触发编辑器自动格式化（如把
<img>包进<p>）；可在插入前后临时禁用编辑器的 DOM 监听逻辑，或使用editor.insertNode()（如有封装 API）替代原生操作
处理光标位于空行或段落开头/结尾的边界情况
用户常点击回车后在空行插入图片，此时 anchorNode 可能是空的 Text 节点（nodeValue === ""），或 anchorOffset === 0 且父节点无前驱兄弟节点——这种情况下 insertBefore 会找不到合法 refNode。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 若
anchorNode.nodeType === Node.TEXT_NODE && anchorNode.nodeValue.trim() === ""，优先取anchorNode.parentNode作为父容器，并用parentNode.childNodes[0]（即第一个子节点）作为refNode，实现“插到段落最前” - 若光标在段落末尾（
anchorOffset === anchorNode.length），且anchorNode是文本节点，则refNode应设为null，此时insertBefore(newNode, null)等价于appendChild - 对空段落（如
<p><br></p>），先移除<br>再插入，否则媒体节点会被挤到换行符后面，造成视觉错位
兼容 Safari 中 Range 与 insertBefore 的时序问题
Safari 在 contenteditable 中对 Range 的处理更严格：若在插入前未显式折叠选区（range.collapse(true)），或插入后未重置光标，后续输入可能覆盖刚插入的媒体节点，或触发不可预期的 DOM 合并。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 插入前务必调用
range.collapse(true)（true表示 collapse 到起点），防止 Safari 将新节点插入到选区中间而非光标处 - 插入后手动设置光标到新节点之后：创建新
Range，用range.setStartAfter(newNode)，再selection.removeAllRanges()+selection.addRange(range) - 避免在
input或beforeinput事件中同步调用insertBefore；改用setTimeout(() => {...}, 0)或queueMicrotask延迟到 DOM 更新后执行
insertBefore，而是判断「此刻该往哪插、插成什么样、插完光标去哪」——这三步每一步都依赖对当前编辑器 DOM 结构和浏览器行为的即时推理，而不是静态模板。 
