Selenium 4.12 起新增原生下载管理能力，需显式启用 enable_downloads 并配合 Grid 参数，才能调用 get_downloadable_files() 和 download_file() 等方法，否则会抛出“WebDriverException: You must enable downloads”错误。
selenium 4.12 起新增原生下载管理能力，需显式启用 `enable_downloads` 并配合 grid 参数，才能调用 `get_downloadable_files()` 和 `download_file()` 等方法，否则会抛出“webdriverexception: you must enable downloads”错误。
在 Selenium 4.12 及更高版本中，浏览器文件下载已从“依赖前端行为模拟”升级为 WebDriver 原生支持的能力。这意味着你不再需要监听网络请求、解析响应头或手动触发 click() + time.sleep() 等不可靠方式——而是可通过标准化 API 安全、可靠地获取待下载项并执行本地保存。但该功能默认关闭，必须同时满足服务端与客户端双重启用条件。
✅ 正确启用下载管理的两个必要条件
-
服务端（Grid / Standalone Server）启用托管下载
启动 Selenium Server（如 selenium-server-4.x.jar）时，必须添加参数：java -jar selenium-server-4.18.1.jar standalone --enable-managed-downloads true
⚠️ 注意：若使用 webdriver.Remote() 连接远程服务（包括 Docker、云平台或本地 Grid），此参数必不可少；若使用 webdriver.Chrome() 直连本地浏览器（即非 Remote 模式），则无需此参数，但仍需客户端启用。
-
客户端（Python 脚本）启用下载能力
在初始化 ChromeOptions 时，必须设置 options.enable_downloads = True（这是关键！旧版 prefs 配置仅影响浏览器 UI 行为，不激活 WebDriver 下载 API）：from selenium import webdriver options = webdriver.ChromeOptions() options.add_argument("--disable-popup-blocking") # ✅ 必须启用：激活 WebDriver 原生下载管理 options.enable_downloads = True # ? 可选：指定默认下载目录（仅影响浏览器 UI，不影响 download_file()） options.add_experimental_option("prefs", { "download.default_directory": r"/Users/abderrahim/Documents/cv_apec", "download.prompt_for_download": False, "safebrowsing.enabled": False # 防止 Chrome 安全拦截 }) # 若连接远程服务（如 Grid） driver = webdriver.Remote( command_executor="http://localhost:4444/wd/hub", options=options ) # 若本地启动 Chrome（无需 Grid） # driver = webdriver.Chrome(options=options)
✅ 使用下载 API 的标准流程
启用后，即可按三步安全操作：
# 1. 导航到含下载链接的页面
driver.get("https://example.com/resume.pdf")
# 2. 获取当前页面所有可下载资源（返回 DownloadableFile 对象列表）
files = driver.get_downloadable_files()
print(f"发现 {len(files)} 个待下载文件")
for f in files:
print(f"- {f.name} ({f.url}, {f.mime_type})")
# 3. 下载指定文件到目标路径（支持自定义文件名和目录）
if files:
target_path = "/Users/abderrahim/Documents/cv_apec/fetched_resume.pdf"
driver.download_file(files[0], target_path) # 自动处理重命名、覆盖、权限等
print(f"✅ 已下载至: {target_path}")? download_file(downloadable_file, target_path) 会自动处理：
- 文件重命名冲突（如添加 (1) 后缀）
- 权限检查与创建缺失目录
- HTTP 重定向与认证头透传
- 下载超时与失败重试（默认 60 秒）
⚠️ 常见误区与注意事项
❌ 错误：仅配置 download.default_directory 但未设 options.enable_downloads = True → 报错 You must enable downloads
-
❌ 错误：使用 driver.find_element(...).click() 触发下载后，立即调用 get_downloadable_files() → 返回空列表（因下载尚未被 WebDriver 捕获）
✅ 正确做法：等待 driver.get_downloadable_files() 返回非空结果（建议加显式等待）：from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC WebDriverWait(driver, 30).until( lambda d: len(d.get_downloadable_files()) > 0 ) ❌ 错误：在无 Grid 环境下仍添加 --enable-managed-downloads true → 启动失败（该参数仅对 standalone/node 有效）
✅ 推荐：始终关闭 safebrowsing.enabled，避免 Chrome 对 .exe/.pdf 等文件弹出“不安全”警告阻断下载。
✅ 总结
Selenium 的原生下载能力是稳定自动化文件采集的关键升级。请严格遵循：
? 服务端：--enable-managed-downloads true（Remote 场景必需）
? 客户端：options.enable_downloads = True（绝对不可省略）
? 调用链：get_downloadable_files() → 显式等待 → download_file()
完成配置后，即可告别不可靠的 time.sleep() 和文件系统轮询，构建健壮、可维护的下载工作流。
