Puppeteer-Sharp 在 Firefox 中页面脚本注入的限制与解决方案

背景与问题分析

Puppeteer-Sharp 作为 .NET 平台的浏览器自动化工具，在跨浏览器支持方面存在一些差异。近期开发者反馈，在 Firefox 浏览器中使用 EvaluateFunctionOnNewDocumentAsync 方法时遇到执行失败的问题，而同样的代码在 Chromium 内核浏览器中却能正常工作。

经过技术验证，这个问题源于 Firefox 对 Puppeteer 某些功能的原生支持限制。具体表现为：

1. EvaluateFunctionOnNewDocumentAsync 方法在 Firefox 环境下无法正常工作
2. 作为替代方案的 FrameNavigated 事件监听在 Firefox 中同样失效
3. 仅 EvaluateFunctionAsync 方法可以正常执行，但无法满足"在每个新框架中自动执行脚本"的需求

技术原理剖析

在 Chromium 内核浏览器中，Puppeteer 通过 DevTools 协议提供了完善的页面生命周期控制能力。其中：

• EvaluateFunctionOnNewDocumentAsync 利用了页面创建时的初始化阶段注入脚本
• FrameNavigated 事件依赖于框架导航的完整生命周期通知机制

而 Firefox 的实现（通过 Firefox 的远程协议）目前尚未完整实现这些高级特性。这导致：

1. 缺乏文档初始化阶段的脚本注入接口
2. 框架导航事件的通知机制不完善
3. 只能支持基本的页面交互功能

可行的解决方案

虽然 Firefox 存在这些限制，但开发者仍可以通过以下方式实现类似功能：

方案一：轮询检查与脚本注入

// 创建定时器定期检查新框架
var timer = new Timer(async _ => {
    var frames = page.Frames;
    foreach(var frame in frames)
    {
        if(!injectedFrames.Contains(frame))
        {
            await frame.EvaluateFunctionAsync("() => { alert(1); }");
            injectedFrames.Add(frame);
        }
    }
}, null, 0, 1000); // 每秒检查一次

方案二：基于内容加载事件的脚本注入

page.Load += async (sender, e) => {
    foreach(var frame in page.Frames)
    {
        try {
            await frame.EvaluateFunctionAsync("() => { alert(1); }");
        } catch {
            // 处理可能的执行异常
        }
    }
};

最佳实践建议

1. 浏览器检测与分支处理：实现时应先检测浏览器类型，对 Firefox 采用特殊处理
2. 错误处理强化：增加更完善的异常捕获和重试机制
3. 性能考量：轮询方案需注意执行频率，避免过高CPU占用
4. 功能降级设计：对于非关键功能，考虑在Firefox中提供简化实现

未来展望

随着 Firefox 对自动化测试支持能力的持续改进，预计未来版本可能会逐步完善这些功能接口。开发者可以关注 Puppeteer-Sharp 的更新日志，及时获取跨浏览器兼容性的改进信息。

对于当前项目，建议评估 Firefox 支持的必要性，如果必须支持，则采用上述解决方案；否则可以考虑暂时限定使用 Chromium 内核浏览器。