本文详解如何在 Chrome 无头模式下正确加载并截图 Chrome 扩展的 popup.html 页面，重点解决因旧版 --headless 参数导致扩展页面白屏的问题，并提供稳定可靠的等待与截图实践方案。
本文详解如何在 chrome 无头模式下正确加载并截图 chrome 扩展的 popup.html 页面，重点解决因旧版 `--headless` 参数导致扩展页面白屏的问题，并提供稳定可靠的等待与截图实践方案。
在使用 Selenium 自动化测试 Chrome 扩展（如 popup、options 或 background 页面）时，开发者常遇到一个典型问题：启用传统 --headless 模式后，chrome-extension:// 协议页面无法正常渲染，最终生成空白截图（如 1.png 全黑或纯白）。而一旦切换回有界面模式（即移除 --headless），页面即可正常显示——这说明问题并非扩展本身或路径错误，而是 Chromium 在旧版无头实现中对扩展上下文（extension context）的支持存在限制。
✅ 根本原因与关键修复
自 Chromium 109+（对应 Chrome 109 及更新版本）起，官方引入了新版无头模式 --headless=new，它重构了渲染架构，完整支持扩展页面生命周期、DOM 构建、CSS 渲染及 JavaScript 执行。相较已被标记为“deprecated”的旧版 --headless（即 --headless=chrome），--headless=new 启用了更完整的浏览器上下文，包括对 chrome-extension:// 协议的原生支持。
因此，只需将启动参数更新为：
options.add_argument("--headless=new") # ✅ 推荐：启用新版无头模式⚠️ 注意：若未显式指定 new，且 Chrome 版本 ≥109，Selenium 可能仍默认使用旧模式（尤其在未升级 WebDriver 或选项配置不明确时），导致扩展页面静默失败。
? 完整可运行示例（含显式等待）
仅启用 --headless=new 并不足以保证截图稳定性——扩展页面可能因资源异步加载、React/Vue 框架挂载延迟或 DOM 尚未就绪而截取到中间状态。因此，必须配合显式等待（WebDriverWait）确保关键元素出现：
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from webdriver_manager.chrome import ChromeDriverManager
options = Options()
options.add_extension("ext.crx")
options.add_argument("--headless=new") # ✅ 必须使用新版无头模式
options.add_argument("--window-size=1920,1080")
options.add_argument("--no-sandbox")
options.add_argument("--disable-dev-shm-usage")
driver = webdriver.Chrome(
service=Service(ChromeDriverManager().install()),
options=options
)
try:
driver.get("chrome-extension://<your-extension-id>/popup.html")
# 等待页面中某个标志性元素（如 <body> 或特定 class 的容器）可见
WebDriverWait(driver, 10).until(
EC.presence_of_element_located((By.TAG_NAME, "body"))
)
# 可选：等待更具体的 UI 元素（如按钮、标题）
# WebDriverWait(driver, 10).until(
# EC.visibility_of_element_located((By.ID, "popup-root"))
# )
driver.save_screenshot("popup_rendered.png")
print("✅ Screenshot saved successfully.")
finally:
driver.quit()? 重要注意事项
- 替换 <your-extension-id> 为实际扩展 ID（可通过 chrome://extensions 开启开发者模式后查看）；
- .crx 文件需为合法打包扩展（非开发模式下的解压目录），否则 add_extension() 会抛出异常；
- 若扩展依赖后台脚本或权限（如 activeTab, storage），请确保 manifest.json 中已声明，且无跨域/内容安全策略（CSP）拦截；
- 避免混用 --headless 和 --headless=new ——后者已完全取代前者；
- 在 CI/CD 环境（如 GitHub Actions、Docker）中，务必确认 Chrome 版本 ≥109，并安装对应 chromedriver。
✅ 总结
Chrome 扩展页面在 Selenium 无头模式下白屏，本质是旧版 --headless 对扩展上下文支持缺失所致。升级至 --headless=new 是必要前提，再辅以 WebDriverWait 确保 DOM 就绪，即可实现稳定、可复现的自动化截图与测试。该方案兼顾兼容性与可靠性，是当前 Chrome 扩展 E2E 测试的最佳实践。
