PuppeteerSharp Headless为true时报127.0.0.1端口主动拒绝错误如何解决

该问题出现Headless=false正常、true报错的核心原因是：非无头模式下Chrome/Chromium会自动处理用户目录锁冲突、进程复用等异常，而无头模式无交互逻辑，遇到这类问题会直接崩溃，导致PuppeteerSharp无法和浏览器建立调试连接，和防火墙无关的概率极高，可按以下步骤逐一排查：

1. 清理用户目录残留进程锁 #

• 首先关闭所有Chromium/Chrome后台进程，删除你配置的./user-data-dir目录下的SingletonLock、SingletonCookie、SingletonSocket三个文件，也可以直接删除整个user-data-dir目录让程序重新生成，避免之前非无头模式启动留下的进程锁导致无头模式启动失败。
• 启动参数追加无头模式专属兼容参数，规避权限类问题：

browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
    Headless = true,
    UserDataDir = Path.Combine(".", "user-data-dir"),
    Args = new [] { "--no-sandbox", "--disable-dev-shm-usage" }
});

2. 手动指定远程调试端口 #

• 无头模式下PuppeteerSharp默认随机选择端口和浏览器通信，可能出现端口被占用、系统端口限制导致连接失败的情况，可以手动固定调试端口：

browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
    Headless = true,
    UserDataDir = Path.Combine(".", "user-data-dir"),
    Args = new [] { "--remote-debugging-port=9222", "--no-sandbox", "--disable-dev-shm-usage" }
});

• 指定端口后可通过命令行手动启动Chrome验证浏览器本身是否正常：
  chrome --headless=new --user-data-dir=./user-data-dir --remote-debugging-port=9222

3. 修正用户目录路径权限 #

• 确认当前程序运行账户对./user-data-dir路径有读写权限，避免权限不足导致浏览器启动时无法写入配置文件直接崩溃。
• 尽量使用绝对路径代替相对路径，避免工作目录变动导致路径识别错误：
  UserDataDir = Path.GetFullPath(Path.Combine(".", "user-data-dir"))

4. 版本兼容校验 #

旧版本PuppeteerSharp存在无头模式和用户目录兼容的已知Bug，建议升级到最新稳定版，同时确认PuppeteerSharp自动下载的Chromium版本和当前调用的版本匹配，不要混用系统安装的Chrome和Puppeteer自带的Chromium。

额外排查点 #

如果以上步骤都无效，可以临时关闭杀毒软件的进程拦截规则测试，部分杀毒软件会拦截无头模式的Chrome启动，不会触发防火墙提醒。

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