Chrome Manifest V3扩展：Mutation Observer元素可见性检测问题及优化

一、解决"querySelector is not a function"错误 #

这个错误的根源是mutation.addedNodes里的节点不都是DOM元素——它可能包含文本节点、注释节点这类非元素节点，这些节点没有querySelector方法。修复方式很简单：先判断节点是否为元素节点（nodeType === 1），再执行后续操作。

另外你的类名匹配逻辑也有隐患：用className == cName只能匹配元素只有这个单一类名的情况，如果元素有多个类名就会失效，建议改用classList.contains()来判断。

修复后的两个函数如下：

function findSelectorPlaceholder(selector) {
  const observerS = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      if (mutation.addedNodes.length > 0) {
        for (let i = 0; i < mutation.addedNodes.length; i++) {
          const node = mutation.addedNodes[i];
          // 只处理元素节点
          if (node.nodeType !== 1) continue;
          const elm = node.querySelector(selector);
          if (elm && window.getComputedStyle(elm).display !== "none") {
            console.log("Element is visible!");
            placeBtn();
          }
        }
      }
    });
  });
  observerS.observe(document.body, {
    childList: true,
    subtree: true,
  });
}

function findClassPlaceholder(cName) {
  const mutationObserver1 = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      if (mutation.addedNodes.length > 0) {
        for (let i = 0; i < mutation.addedNodes.length; i++) {
          const node = mutation.addedNodes[i];
          // 只处理元素节点
          if (node.nodeType !== 1) continue;
          if (node.classList.contains(cName)) {
            console.log("Class Found!");
            placeBtn();
          }
        }
      }
    });
  });
  mutationObserver1.observe(document.body, {
    childList: true,
    subtree: true,
  });
}

二、合并两个函数的可行方案 #

类名查找本质上可以转化为CSS选择器（.类名），所以我们可以把两个函数合并成一个通用的元素观察函数，以下是两种实用方案：

方案1：统一基于CSS选择器实现 #

这种方案最简洁，调用时如果要匹配类名，直接传入.your-class-name即可：

function setupElementObserver(selector, checkVisibility = true) {
  const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      if (mutation.addedNodes.length === 0) return;
      
      for (const node of mutation.addedNodes) {
        if (node.nodeType !== 1) continue;
        
        // 检查节点本身或后代是否匹配选择器
        let targetElm;
        if (node.matches(selector)) {
          targetElm = node;
        } else {
          targetElm = node.querySelector(selector);
        }
        
        if (!targetElm) continue;
        
        // 可选的可见性检查
        if (checkVisibility) {
          const style = window.getComputedStyle(targetElm);
          if (style.display === "none" || style.visibility === "hidden") {
            return;
          }
        }
        
        console.log("Target element found!");
        placeBtn();
      }
    });
  });
  
  observer.observe(document.body, {
    childList: true,
    subtree: true,
  });
  
  // 页面加载完成后先检查一次，避免错过初始已存在的元素
  const initialElm = document.querySelector(selector);
  if (initialElm) {
    if (!checkVisibility || window.getComputedStyle(initialElm).display !== "none") {
      placeBtn();
    }
  }
}

// 调用示例：
// 匹配复合选择器
setupElementObserver("#some-id .some-class");
// 匹配类名（直接传类选择器），跳过可见性检查
setupElementObserver(".target-class", false);

方案2：保留类名/选择器两种模式（通过参数区分） #

如果希望调用时直接传入类名字符串（不带.），可以给函数加一个参数标识匹配类型：

function setupElementObserver(matchConfig) {
  const { type, value, checkVisibility = true } = matchConfig;
  // 转化为统一的CSS选择器
  let selector;
  if (type === "class") {
    selector = `.${value}`;
  } else if (type === "selector") {
    selector = value;
  } else {
    console.error("Invalid match type");
    return;
  }
  
  const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      if (mutation.addedNodes.length === 0) return;
      
      for (const node of mutation.addedNodes) {
        if (node.nodeType !== 1) continue;
        
        let targetElm;
        if (node.matches(selector)) {
          targetElm = node;
        } else {
          targetElm = node.querySelector(selector);
        }
        
        if (!targetElm) continue;
        
        if (checkVisibility) {
          const style = window.getComputedStyle(targetElm);
          if (style.display === "none" || style.visibility === "hidden") {
            return;
          }
        }
        
        console.log("Target element found!");
        placeBtn();
      }
    });
  });
  
  observer.observe(document.body, {
    childList: true,
    subtree: true,
  });
  
  // 初始元素检查
  const initialElm = document.querySelector(selector);
  if (initialElm) {
    if (!checkVisibility || window.getComputedStyle(initialElm).display !== "none") {
      placeBtn();
    }
  }
}

// 调用示例：
// 基于选择器匹配
setupElementObserver({
  type: "selector",
  value: "#main-container .btn-area",
  checkVisibility: true
});
// 基于类名匹配
setupElementObserver({
  type: "class",
  value: "target-placeholder",
  checkVisibility: false
});

额外优化建议 #

1. 避免重复注入按钮：当前逻辑每次检测到元素都会调用placeBtn()，可能导致按钮重复添加。建议在placeBtn()里先检查目标位置是否已存在按钮，或者给已处理的元素加标记（比如data-injected="true"），避免重复操作。
2. 性能优化：如果页面DOM变更频繁，可以考虑给MutationObserver添加attributeFilter等配置，减少不必要的回调触发。

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