使用Python+Selenium无头模式ChromeDriver下载PDF无响应求助

我之前也踩过这个无头Chrome下载PDF的坑！GUI模式下正常，但无头模式就没反应，核心原因是Chrome的无头模式默认配置和GUI差异很大，尤其是文件下载和PDF处理这块，咱们一步步来解决：

1. 关键配置：修改ChromeOptions，强制下载PDF而非预览 #

无头模式下Chrome默认会用内置的PDF查看器打开文件，而不是直接下载。同时需要明确指定下载路径，避免系统默认路径找不到文件。这里是核心配置代码：

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By
import os
import time

def get_headless_chrome_driver(download_folder):
    # 确保下载目录存在
    if not os.path.exists(download_folder):
        os.makedirs(download_folder)
    download_path = os.path.abspath(download_folder)

    chrome_options = Options()
    # 一定要用新的无头模式参数！旧的--headless有大量兼容性问题
    chrome_options.add_argument("--headless=new")
    chrome_options.add_argument("--disable-gpu")
    chrome_options.add_argument("--no-sandbox")  # 解决Linux/macOS下的权限问题

    # 配置下载行为
    prefs = {
        "download.default_directory": download_path,  # 指定下载路径
        "download.prompt_for_download": False,  # 禁止弹出下载确认框
        "download.directory_upgrade": True,
        "plugins.always_open_pdf_externally": True,  # 强制下载PDF，不打开预览
        "plugins.plugins_disabled": ["Chrome PDF Viewer"]  # 彻底禁用内置PDF查看器
    }
    chrome_options.add_experimental_option("prefs", prefs)

    # 可选：添加用户代理，模拟真实浏览器，避免被网站检测无头模式
    chrome_options.add_argument(
        "--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
    )

    return webdriver.Chrome(options=chrome_options)

# 测试代码
if __name__ == "__main__":
    driver = get_headless_chrome_driver("./pdf_downloads")
    try:
        driver.get("你的目标网页URL")
        # 替换成你实际的下载按钮定位方式（比如ID、XPath、LinkText）
        download_btn = driver.find_element(By.XPATH, "//a[contains(text(), '下载PDF')]")
        download_btn.click()

        # 等待下载完成（可根据文件大小调整时间，或写循环检测文件）
        time.sleep(6)

        # 检查下载结果
        files = os.listdir("./pdf_downloads")
        if files:
            print(f"成功下载文件：{files}")
        else:
            print("未检测到下载文件，可能需要延长等待时间")
    finally:
        driver.quit()

2. 必查事项：确保Chrome与ChromeDriver版本完全匹配 #

这是很多人忽略的关键点！如果你的Chrome浏览器是118版本，ChromeDriver必须也是118.x.x.x版本，版本不匹配会导致各种诡异的无响应问题。你可以通过chrome://version/查看Chrome版本，然后下载对应版本的ChromeDriver。

3. 权限与路径问题 #

• 下载路径一定要用绝对路径，相对路径可能会因为程序运行目录不同导致找不到文件
• Linux/macOS环境下，确保下载目录有读写权限，避免因为权限不足导致下载失败
• 如果是Linux服务器，可能需要安装Chrome的依赖库，比如libnss3-dev、libgconf-2-4、libxss1等，否则无头Chrome可能无法启动

4. 优化等待逻辑（可选） #

上面的代码用了time.sleep()，但更可靠的方式是循环检查下载目录是否出现目标文件，避免固定等待时间的不确定性：

def wait_for_download(download_folder, timeout=30):
    start_time = time.time()
    while time.time() - start_time < timeout:
        # 过滤掉Chrome的临时下载文件（.crdownload后缀）
        files = [f for f in os.listdir(download_folder) if not f.endswith(".crdownload")]
        if files:
            return files[0]
        time.sleep(1)
    return None

# 在点击下载后调用
downloaded_file = wait_for_download("./pdf_downloads")
if downloaded_file:
    print(f"下载完成：{downloaded_file}")
else:
    print("下载超时")

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