chrome 在无头模式下无法下载文件，根本原因在于云环境（如 github actions、aws）缺乏图形界面支持，且 --window-size 参数在 headless 模式下对下载行为有隐式影响；需结合运行时窗口尺寸设置与虚拟帧缓冲（xvfb）协同解决。
chrome 在无头模式下无法下载文件，根本原因在于云环境（如 github actions、aws）缺乏图形界面支持，且 --window-size 参数在 headless 模式下对下载行为有隐式影响；需结合运行时窗口尺寸设置与虚拟帧缓冲（xvfb）协同解决。
在 Selenium Java 中使用 Chrome 的 headless 模式进行自动化文件下载时，开发者常遇到“本地可下载、CI/CD 环境（如 GitHub Actions、AWS EC2）却完全静默失败”的问题。这并非 Selenium 或 Chrome 版本退化所致，而是由 headless 模式在无显示环境下的行为限制引发——Chrome 内部下载逻辑依赖于有效的浏览器窗口上下文（如尺寸、焦点、UI 可见性），而纯 headless 启动时若仅靠 --window-size 命令行参数，该尺寸不会真正注入到渲染上下文中，导致下载触发器被忽略或拦截。
✅ 正确配置要点
1. 移除无效的 --window-size 启动参数，改用运行时设置
命令行参数 --window-size=1920,1080 在 headless 模式下不生效（Chrome 官方文档明确说明：该参数仅对非 headless 有效）。应删除该参数，并在驱动初始化后立即调用：
driver.manage().window().setSize(new Dimension(1920, 1080));
⚠️ 注意：此操作必须在 new ChromeDriver(...) 创建后、执行任何页面交互之前完成，否则可能因窗口未就绪而抛出 WebDriverException。
2. 必须启用虚拟显示（Xvfb）——尤其在 Linux 云环境
GitHub Actions（ubuntu-latest）、AWS EC2（Amazon Linux/Ubuntu）等无图形服务器默认无 X11 显示服务。即使启用了 headless，Chrome 下载模块仍可能因缺少底层图形上下文而降级或拒绝写入磁盘。
推荐在 CI 脚本中前置启动 Xvfb：
# GitHub Actions 示例（在 job steps 中）
- name: Start Xvfb
run: |
sudo apt-get update && sudo apt-get install -y xvfb
Xvfb :99 -screen 0 1920x1080x24 > /dev/null 2>&1 &
export DISPLAY=:99
随后在 Java 代码中无需额外指定 --headless（Xvfb 提供了伪 GUI 上下文，Chrome 会自动 fallback 到 headless-like 行为），但仍建议保留 --headless=new 以确保兼容性。
3. 完整、健壮的 ChromeOptions 配置（Selenium 4+ 推荐写法）
String downloadDir = "/tmp/downloads";
Files.createDirectories(Paths.get(downloadDir));
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");
options.addArguments("--disable-gpu");
options.addArguments("--disable-extensions");
options.addArguments("--disable-plugins");
// ✅ 关键：下载偏好通过 setExperimentalOption 设置
Map<string object> prefs = Map.of(
"download.default_directory", downloadDir,
"download.prompt_for_download", false,
"download.directory_upgrade", true,
"safebrowsing.enabled", false,
"profile.default_content_setting_values.notifications", 2
);
options.setExperimentalOption("prefs", prefs);
// ✅ 启动驱动后立即设置窗口尺寸（必须！）
WebDriver driver = new ChromeDriver(options);
driver.manage().window().setSize(new Dimension(1920, 1080)); // 触发内部 UI 上下文初始化
// ✅ 验证下载目录权限（云环境常见坑）
Runtime.getRuntime().exec("chmod -R 777 " + downloadDir);</string>
⚠️ 并行执行注意事项（重要更新）
若采用 TestNG/JUnit5 多线程并发运行多个 ChromeDriver 实例，请注意：
- Xvfb 不支持多 Display Server 共存：单个 :99 显示无法被多个 Chrome 进程安全共享；
- 推荐方案：为每个线程分配独立 Xvfb 实例（如 :99, :100, :101…），并通过 export DISPLAY=:xxx 动态绑定；
- 更优实践：改用 --headless=new + --remote-debugging-port + 无 Xvfb 方案，并确保 download.default_directory 为绝对路径且线程隔离（例如基于 Thread ID 动态创建子目录）。
✅ 总结
Chrome headless 下载失败的本质是UI 上下文缺失，而非网络或权限问题。解决路径唯一且明确：
① 删除无效 --window-size 参数；
② 启动后调用 setSize() 注入尺寸；
③ 在无显示云环境中强制启用 Xvfb（或严格验证 headless 兼容性）；
④ 下载目录需绝对路径、可写、线程安全。
遵循上述三步，即可在 GitHub Actions、AWS、Docker 容器等全场景稳定实现 headless 文件下载。
