ChromeDriver 升级至 117+ 后，--incognito 模式会重置下载策略，导致 download.prompt_for_download=false 失效并强制弹出“Save As”对话框；本文详解根本原因、兼容性修复方案及推荐的无痕+自动下载双模配置。
chromedriver 升级至 117+ 后，`--incognito` 模式会重置下载策略，导致 `download.prompt_for_download=false` 失效并强制弹出“save as”对话框；本文详解根本原因、兼容性修复方案及推荐的无痕+自动下载双模配置。
自 Chrome 117 起（2023年8月发布，当前已迭代至 Chrome 121+），Google 对 Chromium 的隐私沙箱与下载策略进行了深度重构。其中一项关键变更：在无痕（Incognito）模式下，所有 profile 级别偏好设置（包括 prefs 中定义的下载行为）将被忽略或强制重置为安全默认值。这意味着即使你通过 setExperimentalOption("prefs", chromePrefs) 显式设置了：
chromePrefs.put("download.prompt_for_download", false);
chromePrefs.put("download.default_directory", "C:\local_files");
chromePrefs.put("profile.default_content_setting_values.automatic_downloads", 1);这些配置在 --incognito 或 incognito=new 启动时完全不生效——浏览器会无视 default_directory，也不禁用提示，而是强制唤起系统级“Save As”对话框，从而阻断自动化流程。
✅ 根本原因定位
-
--incognito模式本质是启动一个临时、隔离、无持久化 profile 的浏览器上下文； - Chrome 117+ 将
automatic_downloads权限纳入「站点权限（Site Permissions）」统一管控，并禁止在无痕模式下授予永久性自动下载权限； -
profile.content_settings.exceptions.automatic_downloads.*.setting等旧式键名已被弃用，新版需通过 Chrome DevTools Protocol（CDP）动态授予权限。
✅ 推荐解决方案（三选一，按优先级排序）
✅ 方案一：移除 --incognito —— 最简稳定（生产首选）
若业务逻辑不要求严格无痕环境（如仅需避免缓存/登录态残留），直接删除 incognito 参数即可恢复下载控制：
// ❌ 移除以下行（及其相关 capability 设置）
// options.addArguments("--incognito");
// options.setCapability("chrome.switches", Arrays.asList("--incognito"));
// ✅ 保留且仅保留必要参数
options.addArguments("--headless=new"); // 推荐使用新版 headless
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");
HashMap<String, Object> chromePrefs = new HashMap<>();
chromePrefs.put("download.default_directory", "C:\local_files");
chromePrefs.put("download.prompt_for_download", false);
chromePrefs.put("download.directory_upgrade", true); // 关键：启用目录升级支持（v115+ 必须）
chromePrefs.put("profile.default_content_setting_values.notifications", 2);
chromePrefs.put("profile.default_content_setting_values.automatic_downloads", 1);
options.setExperimentalOption("prefs", chromePrefs);✅ 验证效果：调用
driver.get("http://my_site.com/download")→ 点击下载按钮 → 文件将静默保存至指定路径，无任何弹窗。
✅ 方案二：保留无痕 + CDP 动态授予权限（高级适用）
若必须使用无痕模式（例如多账号并发、敏感操作隔离），可借助 Chrome DevTools Protocol 在运行时为当前页面显式启用自动下载：
import org.openqa.selenium.devtools.DevTools;
import org.openqa.selenium.devtools.v121.browser.Browser;
import org.openqa.selenium.devtools.v121.browser.model.DownloadBehavior;
import org.openqa.selenium.devtools.v121.emulation.Emulation;
import org.openqa.selenium.devtools.v121.fetch.Fetch;
// ... 初始化 driver 后（含 --incognito）
DevTools devTools = ((ChromeDriver) driver).getDevTools();
devTools.createSession();
// 【关键】为当前页面设置自动下载行为（绕过无痕限制）
devTools.send(Browser.setDownloadBehavior(
DownloadBehavior.ALLOW,
"C:\local_files"
));
// 可选：预设自动下载白名单（针对特定域名）
devTools.send(Emulation.setAutomaticDownloads(true));⚠️ 注意：需引入 selenium-devtools-v121 依赖（Maven）：
<dependency> <groupId>org.seleniumhq.selenium</groupId> <artifactId>selenium-devtools-v121</artifactId> <version>4.19.1</version> <!-- 请匹配你的 Selenium 4.15+ 版本 --> </dependency>
✅ 方案三：改用 --guest 模式替代 --incognito
--guest 启动的是访客模式（Guest Profile），其行为更接近常规 profile，且支持 prefs 下载配置，同时仍具备会话隔离性：
options.addArguments("--guest"); // 替代 "--incognito"
// 其余 prefs 配置保持不变 ✅? 补充说明：
--guest不会加载用户 profile，但允许download.default_directory等策略生效，是 incognito 的轻量级替代方案。
⚠️ 重要注意事项
- 路径必须为绝对路径，且目标目录需预先存在（ChromeDriver 不会自动创建）；
- Windows 下路径分隔符建议使用双反斜杠
\或正斜杠/（如"C:/local_files"）； - 若使用
--headless=new，请确保 Chrome ≥ v116，且避免混用旧版--headless； - Selenium Java 客户端版本建议 ≥ 4.15，以获得完整的 CDP v121 支持；
- 测试前务必确认 Chrome 与 ChromeDriver 主版本号一致（如 Chrome 121.x → ChromeDriver 121.x）。
✅ 总结
ChromeDriver 117+ 的下载弹窗问题并非 Bug，而是 Google 强化隐私策略后的主动设计。无痕模式与静默下载在架构上互斥。生产环境中，优先采用「方案一（移除 incognito）+ 常规 profile 配置」；对强隔离有硬性要求的场景，则应升级技术栈，通过 CDP 动态授权实现无痕下的可控下载。始终牢记：版本匹配、路径规范、CDP 适配，是稳定自动化下载的三大基石。
