Chrome 110+ 版本中，旧版 headless 参数已弃用，导致 download.default_directory 等下载配置在 headless 模式下失效；必须改用 --headless=new 启动参数才能正确启用下载行为。
chrome 110+ 版本中，旧版 `headless` 参数已弃用，导致 `download.default_directory` 等下载配置在 headless 模式下失效；必须改用 `--headless=new` 启动参数才能正确启用下载行为。
在使用 Selenium + ChromeDriver 进行自动化测试时，文件下载功能在常规（有界面）Chrome 模式下通常能正常工作，但一旦切换至 headless 模式，常出现文件未按预期路径下载、甚至完全不触发下载的问题——尤其在 Chrome 109 及更高版本（如题中所述的 110.0.5481.100）中尤为典型。
根本原因在于：自 Chrome 109 起，Google 彻底重构了 headless 实现，原 --headless 标志已被标记为废弃（deprecated），其行为不再兼容完整的浏览器上下文（包括下载管理器、PDF 查看器、弹窗策略等）。新架构要求显式使用 --headless=new 才能启用完整渲染与后台能力，否则 Chrome 会降级为“极简 headless”模式（类似无 UI 的 renderer-only 模式），此时 prefs 中的下载配置（如 download.default_directory 和 download.prompt_for_download）将被忽略，文件默认回退到系统临时目录或 user.dir（即 Java 工作目录）。
✅ 正确做法是：将 options.addArguments("headless"); 替换为
options.addArguments("--headless=new");同时，需确保其他下载相关配置保持有效且语义正确。以下是修复后的完整代码示例（关键修改已高亮）：
public WebDriver createInstance(String browser) {
WebDriver driverInstance = null;
try {
if (browser.equalsIgnoreCase("chrome-headless")) {
WebDriverManager.chromedriver().setup();
ChromeOptions options = new ChromeOptions();
// ✅ 下载偏好配置（注意：路径需为绝对路径，且目录必须存在、有写权限）
Map<String, Object> prefs = new HashMap<>();
prefs.put("profile.default_content_settings.popups", 0);
prefs.put("download.prompt_for_download", false); // 布尔值，非字符串
prefs.put("download.default_directory", "/home/<<USER>>/git/bb-cloud/<<PROJECT>>/src/main/resources");
// ⚠️ 移除无效配置：browser.set_download_behavior 是 Chromium 内部调试参数，Selenium 不支持，应删除
options.setExperimentalOption("prefs", prefs);
// ✅ 使用新版 headless 参数
options.addArguments("--headless=new"); // ← 关键修复！
options.addArguments("--no-sandbox");
options.addArguments("--disable-gpu");
options.addArguments("--disable-dev-shm-usage");
options.addArguments("--allow-insecure-localhost");
options.addArguments("--start-maximized");
options.addArguments("--window-size=1920,1080");
options.setAcceptInsecureCerts(true);
driverInstance = new ChromeDriver(options);
}
} catch (Exception e) {
e.printStackTrace();
}
return driverInstance;
}? 重要注意事项：
- 路径必须为绝对路径，且目标目录需提前创建并赋予当前用户写权限（mkdir -p /path && chmod 755 /path）；
- download.prompt_for_download 应设为 false（布尔类型），而非 "false"（字符串），否则 Chrome 可能忽略该设置；
- 删除 browser.set_download_behavior 这类非标准、未公开的实验性参数——它不属于 ChromeDriver 支持的 prefs，反而可能干扰配置解析；
- 若仍无法下载，请检查页面触发下载的方式：、window.open() 或 fetch + Blob 需配合 Content-Disposition: attachment 响应头；纯前端 Blob URL 在 headless 模式下可能受限，建议优先采用服务端直链下载；
- 推荐在下载后加入健壮性校验逻辑（如轮询文件是否存在、校验文件大小/MD5），避免因异步延迟导致误判。
总结：--headless=new 不仅是参数更新，更是 Chrome 浏览器架构演进的关键标志。升级 Selenium 项目时，务必同步更新启动参数，并重新验证所有依赖完整浏览器上下文的功能（如下载、打印、音频播放、WebRTC 等）。忽视此变更，将导致 headless 自动化流程在新版 Chrome 上大面积失效。
