Selenium 4.12+ 引入了原生下载管理能力，但需显式启用 enable_downloads 选项并配合 Grid 配置，否则调用 get_downloadable_files() 会报错“must enable downloads”。本文详解完整配置流程、代码示例及关键注意事项。
.selenium 4.12+ 引入了原生下载管理能力，但需显式启用 `enable_downloads` 选项并配合 grid 配置，否则调用 `get_downloadable_files()` 会报错“must enable downloads”。本文详解完整配置流程、代码示例及关键注意事项。
在 Selenium 中实现可靠、可编程的文件下载（尤其是 PDF、CSV 等非导航型资源），不能仅依赖传统 download.default_directory 偏好设置——该方式无法被 get_downloadable_files() 识别，且易受浏览器沙箱、弹窗拦截或跨域限制干扰。自 Selenium 4.12 起，官方提供了服务端托管下载（Managed Downloads）机制，它将下载行为纳入 WebDriver 协议层统一管理，支持主动枚举、校验与下载控制。
✅ 正确启用下载管理的三要素
要成功使用 driver.get_downloadable_files() 和 driver.download_file()，必须同时满足以下三项条件：
- 客户端启用：在 ChromeOptions（或其他浏览器 Options）中设置 options.enable_downloads = True；
- 服务端启用：若使用 Selenium Grid（本地 standalone 或远程 node），启动时必须添加 --enable-managed-downloads true 参数；
- 不冲突旧配置：移除或禁用所有可能干扰托管下载的实验性偏好项（如 "download.default_directory"、"download.prompt_for_download"），这些字段在托管模式下由 Selenium 自动处理，手动设置反而会导致未定义行为。
⚠️ 注意：enable_downloads = True 仅对 webdriver.Remote 有效（即连接 Grid/standalone server 的场景）。若直接使用 webdriver.Chrome() 本地驱动，该属性被忽略，且 get_downloadable_files() 不可用——这是当前 Selenium 的设计限制。
? 完整可运行示例（Remote WebDriver）
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
# 1. 配置 ChromeOptions 并启用托管下载
options = Options()
options.enable_downloads = True # ← 关键！必须设为 True
# 可选：指定 Chrome 二进制路径或禁用沙箱等（根据环境调整）
# options.binary_location = "/usr/bin/google-chrome"
# options.add_argument("--no-sandbox")
# 2. 启动 Remote WebDriver（连接本地 standalone server）
# 假设已通过命令行启动：java -jar selenium-server-4.18.0.jar standalone --enable-managed-downloads true
driver = webdriver.Remote(
command_executor="http://localhost:4444", # 默认 standalone 地址
options=options
)
try:
# 3. 导航到含下载链接的页面（例如一个 PDF 下载按钮）
driver.get("https://example.com/resume.pdf") # 或含 <a download> 的 HTML 页面
# 4. 获取当前可下载文件列表（返回 DownloadableFile 对象列表）
downloadable_files = driver.get_downloadable_files()
print(f"发现 {len(downloadable_files)} 个待下载文件")
if downloadable_files:
# 5. 下载第一个文件到指定目录（自动创建子目录，支持绝对/相对路径）
target_dir = "/Users/abderrahim/Documents/cv_apec"
downloaded_path = driver.download_file(downloadable_files[0], target_dir)
print(f"✅ 已保存至: {downloaded_path}")
finally:
driver.quit()? 验证与排错要点
-
Grid 启动命令必须包含 --enable-managed-downloads true：
java -jar selenium-server-4.18.0.jar standalone \ --host 127.0.0.1 \ --port 4444 \ --enable-managed-downloads true
缺少此参数将直接触发 WebDriverException: You must enable downloads... 错误。
-
避免混合使用旧下载配置：
删除或注释掉如下代码（它们与托管下载互斥）：# ❌ 不要再设置这些（在 enable_downloads=True 时无效甚至有害） # options.add_experimental_option("prefs", { # "download.default_directory": r"/path/to/dir", # "download.prompt_for_download": False, # }) 文件可见性要求：get_downloadable_files() 仅返回当前浏览器上下文内已触发但尚未完成的下载任务（例如点击 <a download> 或 window.open('file.pdf') 后）。它不会扫描磁盘目录，也不支持“预设监听 URL 模式”。
下载路径安全性：download_file(file, target_dir) 中的 target_dir 必须是 WebDriver 服务端可写路径（若 Grid 运行在 Docker 或远程服务器上，请确保该路径存在且权限正确）。
✅ 总结
Selenium 的托管下载是面向自动化测试与数据采集场景的现代化解决方案，它解耦了浏览器配置与下载逻辑，提升了稳定性和可观测性。请始终遵循「客户端启用 + 服务端启用 + 避免旧配置」三位一体原则。对于纯本地调试需求，可暂用传统 requests + selenium 提取 URL 的组合方案作为补充；但涉及复杂交互（如登录后动态生成下载 Token），托管下载仍是唯一健壮选择。
