Docker容器中Python Selenium无法下载文件问题排查

这种问题在Docker环境下跑Selenium Chrome太常见了！我帮你梳理几个核心原因和对应的解决办法：

1. 未启用无头模式，Docker无界面环境下Chrome无法正常执行下载流程 #

你的代码里没配置Chrome的无头（headless）模式，Docker容器默认没有图形界面，Chrome在这种环境下如果不启用无头模式，大概率会静默失败——看起来没报错，但实际下载流程根本没触发。

要加上这两个关键参数：

chrome_options.add_argument('--headless=new')  # 新版Chrome的无头模式，比旧版更稳定
chrome_options.add_argument('--disable-gpu')  # 禁用GPU加速，无头模式下完全不需要

2. 未提前创建下载目录，Docker环境下不会自动生成 #

虽然你指定了/tmp/test_download/，但如果这个目录不存在，Chrome在Docker里可能不会自动创建它，导致下载失败但不抛出异常。记得在代码开头先主动创建目录：

import os
my_download_path = "/tmp/test_download/"
os.makedirs(my_download_path, exist_ok=True)  # 不存在就创建，存在则跳过
print("download path: ", my_download_path)

3. 缺少Docker环境下必需的Chrome启动参数 #

Docker里跑Chrome需要禁用沙箱和调整共享内存设置，否则会出现各种静默异常。务必添加这些参数：

chrome_options.add_argument('--no-sandbox')  # 禁用沙箱，Docker环境下必须加
chrome_options.add_argument('--disable-dev-shm-usage')  # 解决Docker共享内存不足的问题

4. ChromeDriver与Chrome版本不匹配 #

这是最容易被忽略的点！Docker镜像里的Chrome版本必须和你使用的ChromeDriver版本完全对应（大版本一致，小版本尽量匹配）。比如如果Docker里是Chrome 118.x，你的ChromeDriver也必须是118.x的版本，否则会出现功能异常，下载就是典型的表现之一。

修正后的完整代码示例 #

import os
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

my_download_path = "/tmp/test_download/"
os.makedirs(my_download_path, exist_ok=True)
print("download path: ", my_download_path)

chrome_options = Options()
# 无头模式配置
chrome_options.add_argument('--headless=new')
chrome_options.add_argument('--disable-gpu')
# Docker必需参数
chrome_options.add_argument('--no-sandbox')
chrome_options.add_argument('--disable-dev-shm-usage')
# 下载相关配置
chrome_options.add_experimental_option('prefs', {
    "download.default_directory": my_download_path,
    "download.prompt_for_download": False,
    "download.directory_upgrade": True,
    "plugins.always_open_pdf_externally": True
})

chrome_driver = "/usr/local/bin/chromedriver"
driver = webdriver.Chrome(options=chrome_options, executable_path=chrome_driver)

# 后续你的下载逻辑...

排查小技巧 #

如果还是有问题，可以进入Docker容器手动检查：

• 执行docker exec -it <容器ID> bash进入容器
• 查看/tmp/test_download/目录是否存在、有没有写入权限：ls -ld /tmp/test_download/
• 在代码里添加浏览器日志打印，查看内部错误：

for entry in driver.get_log('browser'):
    print(entry)

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