使用 Selenium 4.12+ 实现自动化文件下载的完整配置指南

Selenium 4.12 起引入了原生文件下载管理能力，需显式启用 enable_downloads 并配合 –enable-managed-downloads true 启动参数，才能调用 get_downloadable_files() 和 download_file() 等新 API。

selenium 4.12 起引入了原生文件下载管理能力，需显式启用 `enable_downloads` 并配合 `–enable-managed-downloads true` 启动参数，才能调用 `get_downloadable_files()` 和 `download_file()` 等新 api。

在 Selenium 4.12 及更高版本中，文件下载已从“依赖浏览器偏好设置的模拟行为”升级为 WebDriver 原生支持的功能。这意味着：仅配置 download.default_directory 等 chrome 偏好项已不再足够——你必须同时启用 Selenium 的托管式下载机制，否则调用 driver.get_downloadable_files() 将抛出 WebDriverException: You must enable downloads in order to work with downloadable files. 错误。

✅ 正确启用下载功能的三要素

1. 客户端（Python）启用下载管理
   使用 ChromeOptions（或对应浏览器选项类）的 enable_downloads = True 属性（注意：这是属性赋值，非方法调用）：

   from selenium import webdriver  options = webdriver.ChromeOptions() options.add_argument("--disable-popup-blocking") # ⚠️ 注意：以下 prefs 在启用 managed downloads 后将被 Selenium 自动覆盖，可省略（或仅作兼容保留） options.add_experimental_option("prefs", {     "download.default_directory": "/Users/abderrahim/Documents/cv_apec",     "download.prompt_for_download": False,     "download.directory_upgrade": True,     "safebrowsing.enabled": False })  # ✅ 关键：启用 Selenium 托管式下载 options.enable_downloads = True  driver = webdriver.Chrome(options=options)

2. 服务端（Grid / Standalone）启用下载支持
   若你使用 selenium-server（如 standalone 或 node 模式），必须添加启动参数：

   java -jar selenium-server-4.x.jar standalone --enable-managed-downloads true

   对于本地 ChromeDriver（无 Grid 场景），此步自动满足，无需额外操作。

3. 验证与使用下载 API
   启用成功后，即可安全调用新下载接口：

   # 触发下载动作（例如点击下载按钮） download_button = driver.find_element("id", "download-pdf") download_button.click()  # 等待文件出现在可下载列表中（建议加显式等待） from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC  WebDriverWait(driver, 10).until(     lambda d: len(d.get_downloadable_files()) > 0 )  # 获取所有待下载文件对象 downloadable_files = driver.get_downloadable_files() print(f"发现 {len(downloadable_files)} 个可下载文件")  # 下载第一个文件到指定目录（Selenium 自动处理重命名与冲突） target_dir = "/Users/abderrahim/Documents/cv_apec" downloaded_path = driver.download_file(downloadable_files[0], target_dir) print(f"已保存至: {downloaded_path}")

⚠️ 重要注意事项

• 版本强依赖：enable_downloads 和 get_downloadable_files() 仅在 Selenium ≥ 4.12 中可用；低于该版本会报 AttributeError 或 NoSuchAttributeError。
• 路径权限与存在性：download_file() 的 target_directory 必须是已存在的绝对路径，且 WebDriver 进程有写入权限；Selenium 不会自动创建父目录。
• 不支持跨域/认证下载：当前实现仅适用于同源、无需额外身份验证的 http(S) 下载链接；对需 cookie 或 Token 的受保护资源，仍需结合 requests 手动获取。
• 避免混用旧方案：启用 enable_downloads = True 后，download.default_directory 等 prefs 将被忽略；若需兼容旧版逻辑，请统一降级并改用 os.path + time.sleep() 轮询临时目录的方式。

✅ 总结

解决 You must enable downloads 错误的核心在于：客户端启用 options.enable_downloads = True + 服务端（如适用）添加 –enable-managed-downloads true。这是 Selenium 向标准化、可靠化文件下载迈出的关键一步。迁移后，你将获得更稳定的文件发现、自动重命名、并发安全及清晰的异常反馈——告别轮询、规避弹窗、拥抱原生能力。