Chrome 110+ 版本中，旧版 headless 启动参数已弃用，导致 download.default_directory 等下载偏好设置失效；需改用 --headless=new 启动模式，并配合正确配置才能在无界面环境下稳定下载文件。
chrome 110+ 版本中，旧版 `headless` 启动参数已弃用，导致 `download.default_directory` 等下载偏好设置失效；需改用 `--headless=new` 启动模式，并配合正确配置才能在无界面环境下稳定下载文件。
在 Selenium + Java 自动化测试中，使用 Chrome Headless 模式下载文件（如 PDF）时，常遇到文件未按预期保存至指定目录、反而落到了项目根路径（如 /home/user/git/bb-cloud/project/）的问题。该现象并非配置遗漏，而是源于 Chrome 109 起对 Headless 模式的重大重构——传统 headless 标志已被弃用，其行为不再支持完整的浏览器上下文（包括下载管理器），导致 prefs 中设置的 download.default_directory 和 download.prompt_for_download 失效。
✅ 正确配置要点
必须使用 --headless=new 替代 headless
这是解决该问题的核心前提。自 Chrome 109 开始，--headless=new 启用了基于 Chromium 新架构的完整无头模式，完全兼容下载行为、弹窗策略、PDF 渲染等桌面级功能。-
prefs 配置需精简且语义准确
- 移除无效或冗余项（如 browser.set_download_behavior 是 DevTools 协议命令，不能通过 prefs 设置，应删除）；
- download.default_directory 必须为绝对路径，且确保目录存在、有写入权限；
- download.prompt_for_download 应设为 false（布尔值，非字符串）；
- profile.default_content_settings.popups 设为 0 可禁用弹窗拦截，辅助下载触发。
补充必要兼容性参数
保留 --no-sandbox、--disable-dev-shm-usage 等容器/CI 环境必需参数，但避免与新 Headless 冲突（--headless=new 已内置优化）。
✅ 修正后的 Java 示例代码
public WebDriver createInstance(String browser) {
WebDriver driverInstance = null;
try {
if (browser.equalsIgnoreCase("chrome-headless")) {
WebDriverManager.chromedriver().setup();
ChromeOptions options = new ChromeOptions();
// ✅ 关键：使用 --headless=new
options.addArguments("--headless=new");
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");
options.addArguments("--disable-gpu");
options.addArguments("--allow-insecure-localhost");
// ✅ 下载偏好：仅保留必要项，路径为绝对路径
String downloadPath = "/home/<<USER>>/git/bb-cloud/<<PROJECT>>/src/main/resources";
Map<String, Object> prefs = new HashMap<>();
prefs.put("download.default_directory", downloadPath);
prefs.put("download.prompt_for_download", false); // 注意：boolean 类型
prefs.put("profile.default_content_settings.popups", 0);
options.setExperimentalOption("prefs", prefs);
// 可选：窗口尺寸（新 Headless 支持）
options.addArguments("--window-size=1920,1080");
options.setAcceptInsecureCerts(true);
driverInstance = new ChromeDriver(options);
}
} catch (Exception e) {
e.printStackTrace();
}
return driverInstance;
}⚠️ 注意事项
-
路径权限检查：确保 download.default_directory 对应目录存在且当前运行用户具有读写权限（Ubuntu 下可执行 mkdir -p
&& chmod 755 ）； - 避免路径拼接错误：勿在 download.default_directory 中使用相对路径或未转义的变量占位符（如 >），应在运行时动态替换为真实路径；
- 验证下载完成：Headless 下无法感知浏览器下载栏，建议采用轮询文件系统方式验证（例如：等待目标文件出现 + 文件大小非零）；
- 版本兼容性：--headless=new 仅支持 Chrome ≥ 109；若降级使用旧版 Chrome，请回退至 --headless 并接受功能限制（不推荐）。
? 提示：Selenium 4.8+ 已默认适配新 Headless 模式，但驱动配置仍需开发者显式声明 --headless=new。忽略此变更将导致所有依赖下载行为的测试在新版 Chrome 中静默失败。
通过上述调整，即可在 Chrome Headless 新模式下可靠实现文件自动下载与路径控制，显著提升 CI/CD 流水线中文件验证类测试的稳定性与可维护性。
