Rails应用：Capybara+Selenium配置Chrome无头模式下载目录异常

我之前也碰到过一模一样的矛盾情况——要么能成功设置下载目录，但Chrome会弹出窗口；要么能让浏览器无头运行，可下载路径完全不生效。结合你使用的capybara 2.14.2版本，给你一套能同时满足无头静默运行和自定义下载目录的配置方案：

正确的support/env.rb配置代码 #

# 注册一个同时支持无头模式和指定下载目录的自定义Chrome驱动
Capybara.register_driver :chrome_headless_with_download do |app|
  # 定义下载目录，这里用Rails项目下的tmp/downloads，可按需修改
  download_dir = Rails.root.join('tmp', 'downloads').to_s
  # 提前创建目录，避免因目录不存在导致下载失败
  FileUtils.mkdir_p(download_dir)

  # 初始化Chrome配置选项
  chrome_options = Selenium::WebDriver::Chrome::Options.new

  # 添加无头模式参数（适配你的旧版Capybara/Selenium版本）
  chrome_options.add_argument('--headless')
  # 禁用弹窗，解决浏览器弹出的问题
  chrome_options.add_argument('--disable-popup-blocking')
  # 可选：添加no-sandbox参数，多数CI环境需要这个来规避权限限制
  chrome_options.add_argument('--no-sandbox')

  # 配置下载核心偏好，这是让自定义目录生效的关键
  chrome_options.add_preference(
    'download.default_directory', download_dir,
    'download.prompt_for_download', false, # 禁止询问下载路径
    'download.directory_upgrade', true, # 允许自动升级下载目录权限
    'profile.default_content_settings.popups', 0, # 全局禁用弹窗
    'plugins.plugins_disabled', ['Chrome PDF Viewer'] # 防止PDF自动预览，强制下载到目录
  )

  # 创建Capybara驱动实例
  Capybara::Selenium::Driver.new(app, browser: :chrome, options: chrome_options)
end

# 将默认驱动和JS驱动设置为我们自定义的驱动
Capybara.default_driver = :chrome_headless_with_download
Capybara.javascript_driver = :chrome_headless_with_download

为什么之前的配置会冲突？ #

你遇到的核心问题是无头模式参数与下载偏好设置没有正确组合：

• 如果只配置下载偏好而不加--headless，Chrome会以正常交互模式启动，自然会弹出浏览器窗口；
• 如果只加--headless但没配全下载相关偏好（比如漏了download.prompt_for_download或profile.default_content_settings.popups），Chrome无头模式会默认禁用部分交互类配置，导致你的下载目录设置被忽略。

另外，你的capybara版本（2.14.2）比较旧，对应的selenium-webdriver应该是3.x系列，所以要用旧版的--headless参数，而非现在Chrome 96+支持的--headless=new。

额外注意事项 #

• 确保Chrome浏览器版本与selenium-webdriver版本兼容，capybara 2.14.2建议搭配selenium-webdriver 3.141.x版本；
• 下载目录要设置为测试进程有权限写入的路径，用Rails.root.join('tmp', 'downloads')是安全且通用的选择；
• 如果测试涉及PDF下载，plugins.plugins_disabled配置可以避免Chrome自动打开预览，确保文件直接下载到指定目录。

内容的提问来源于stack exchange，提问作者user43395