Laravel/Dusk无头Chrome模式下文件下载失败解决方案咨询

这个问题我之前帮不少开发者解决过，无头Chrome默认会禁用自动下载行为，得调整几个关键配置才能让文件正常下载，一步步来：

1. 配置Chrome启动参数 #

你需要在Dusk的测试配置里添加Chrome的自定义选项，指定下载目录并开启自动下载权限。打开tests/DuskTestCase.php，找到driver方法，修改Chrome驱动的配置：

protected function driver()
{
    $options = (new ChromeOptions)->addArguments([
        '--headless=new', // 用新版无头模式，兼容性更接近GUI
        '--disable-gpu',
        '--window-size=1920,1080',
        '--no-sandbox', // 服务器环境通常需要这个参数
    ]);

    // 设置下载偏好
    $options->setExperimentalOption('prefs', [
        'download.default_directory' => base_path('storage/app/downloads'), // 必须用绝对路径，推荐存在storage目录下
        'download.prompt_for_download' => false, // 禁用下载确认提示
        'profile.default_content_setting_values.automatic_downloads' => 1, // 允许自动下载
        'safebrowsing.enabled' => false, // 关闭安全浏览检查（如果下载文件被标记为"不安全"）
    ]);

    return RemoteWebDriver::create(
        'http://localhost:9515',
        DesiredCapabilities::chrome()->setCapability(
            ChromeOptions::CAPABILITY,
            $options
        )
    );
}

这里一定要用绝对路径，无头模式下相对路径很容易找不到正确的下载位置，base_path()可以帮你生成项目根目录的绝对路径，避免路径错误。

2. 确保下载目录有写入权限 #

先创建你指定的下载目录（比如storage/app/downloads），然后给运行测试的用户分配写入权限：

mkdir -p storage/app/downloads
chmod -R 755 storage/app/downloads
# 如果是Linux服务器，可能需要调整用户组匹配web进程
chown -R www-data:www-data storage/app/downloads

3. 测试里验证下载结果 #

触发下载操作后，要给文件留够下载时间，再检查文件是否存在：

// 触发下载按钮点击
$browser->click('#download-button');

// 根据文件大小调整等待时间，避免还没下载完就检查
sleep(3);

// 验证文件是否存在
$this->assertFileExists(base_path('storage/app/downloads/your-target-file.pdf'));

// 或者用Laravel文件系统门面更优雅
$this->assertTrue(Storage::disk('local')->exists('downloads/your-target-file.pdf'));

常见问题排查 #

• 如果还是下载失败，检查是不是用了旧版无头参数--headless，换成--headless=new试试，新版无头模式修复了很多和GUI模式不一致的兼容性问题。
• 确认下载的文件名和你检查的完全一致，有些服务器会生成带时间戳或随机字符串的文件名，需要动态获取或者提前明确文件名规则。
• CI/CD环境运行测试时，确保Chrome版本是最新的，旧版Chrome的无头模式限制更多。

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