React组件两次渲染导致Prismic动态词替换DOM错乱问题排查

数据老陈

2026-8-27

两次渲染及结构错乱的核心原因

开发环境下如果开启了React.StrictMode，React会刻意重复执行组件渲染、Effect清理/执行流程，用来检测不符合规范的副作用代码，这是最常见的双触发来源。
实现逻辑违反React渲染规则，才是结构错乱的根本原因：
- 你在Effect里直接手动修改真实DOM的innerHTML，但React的虚拟DOM完全感知不到这次修改，始终保存着富文本初始渲染的DOM结构快照。
- 当组件二次渲染时，React会对比虚拟DOM快照和真实DOM的差异，对真实DOM做增量更新——这时候你之前手动插入的动态词span不在React的快照里，就会被React的diff逻辑错误修改属性、甚至部分删除。
- 等二次触发的Effect拿到错乱后的innerHTML再执行替换时，会对已经处理过的动态词span做重复匹配、嵌套替换，直接导致整个HTML结构失效。
- 额外隐患：你用全局id选择器#textblock查找DOM，如果页面里同时存在多个该组件实例，会直接出现选择冲突；Effect依赖只加了dynamic_words，如果text属性更新，处理逻辑不会重新执行，也会出现内容和动态词不匹配的问题。

最优解决方案

彻底放弃「渲染完成后手动改innerHTML」的思路，在React渲染链路里直接完成动态词的替换，从根源上避免虚拟DOM和真实DOM不一致的问题：

优先用Prismic RichText组件提供的自定义序列化/自定义组件能力，在文本节点渲染阶段就完成动态词匹配和替换，直接渲染出带data属性、绑定交互的span节点，完全不需要手动操作DOM。
参考实现代码：

import React from 'react';

// 工具：按动态词拆分纯文本片段，做正则转义避免特殊字符导致匹配失效
const splitContentByDynamicWords = (plainText, dynamicWords) => {
  if (!dynamicWords?.length) return [plainText];
  // 转义动态词里的正则特殊字符
  const escapedWords = dynamicWords.map(item => 
    item.word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
  );
  const matchReg = new RegExp(`(${escapedWords.join('|')})`, 'g');
  return plainText.split(matchReg).filter(Boolean);
};

export const ArticleBodyText = ({ text, dynamic_words }) => {
  // 自定义富文本渲染规则
  const customRichTextComponents = {
    paragraph: ({ children }) => <p>{children}</p>,
    // 接管所有纯文本节点的渲染
    text: ({ text: nodeText }) => {
      const contentFragments = splitContentByDynamicWords(nodeText, dynamic_words);
      return contentFragments.map((fragment, index) => {
        const matchedDynamicWord = dynamic_words?.find(item => item.word === fragment);
        // 匹配到动态词就渲染带属性和交互的span
        if (matchedDynamicWord) {
          return (
            <span
              key={index}
              className="dynamic-word"
              data-related-image={matchedDynamicWord.image.url}
              onClick={() => {
                // 点击展示关联图片的逻辑
              }}
            >
              {fragment}
            </span>
          );
        }
        // 普通文本直接渲染
        return <React.Fragment key={index}>{fragment}</React.Fragment>;
      });
    }
  };

  return (
    <TextBlock>
      <RichText render={text} components={customRichTextComponents} />
    </TextBlock>
  );
};

该方案的优势：
- 完全符合React单向数据流规则，所有DOM都由React渲染生成，不管组件重渲染多少次都不会出现结构错乱
- 没有DOM查询、innerHTML写入操作，不存在XSS注入风险
- 不需要依赖全局id选择器，多组件实例同时存在也不会冲突
- props（text/dynamic_words）任意一个更新，都会自动重新计算渲染动态词，不会出现内容不匹配的问题

注意：不要通过关闭React严格模式来回避问题，严格模式只是提前暴露了你代码里的副作用隐患，就算关了严格模式，生产环境下只要组件触发重渲染（比如父组件更新、路由切换等场景），手动改DOM导致的结构错乱问题依然会出现。

内容的提问来源于stack exchange，提问作者Mauro