告别Selenium弹窗噩梦：Playwright实现无头浏览器文件自动下载实战

1. 项目概述：为什么我们要告别Selenium？

如果你做过Web自动化测试或者数据抓取，尤其是涉及到文件下载的场景，那你大概率经历过“弹窗噩梦”。浏览器原生的“另存为”对话框，就像一堵无法逾越的高墙，横亘在你的自动化脚本和本地文件之间。Selenium作为老牌自动化工具，在处理这类交互式系统弹窗时，显得力不从心。你不得不借助AutoIt、PyAutoGUI这类基于坐标模拟的桌面自动化工具，脚本变得脆弱、跨平台性差，维护成本直线上升。

这个项目要解决的，正是这个痛点。它的核心是：利用Playwright这一现代浏览器自动化库，结合Python，实现无需人工干预、稳定可靠的无头浏览器文件自动下载。这里的“无头”指的是没有图形界面的浏览器，它运行在后台，更节省资源，更适合自动化任务。而“告别Selenium弹窗噩梦”则直击了传统方案的软肋。

我最近在一个数据报表自动归档的项目中，就遇到了这个问题。每天需要从几十个内部系统页面下载Excel和PDF报表，用Selenium写了一半，全卡在下载弹窗上。后来切换到Playwright，配合其强大的下载事件监听和路径控制API，整个流程变得异常丝滑。这篇文章，我就把这个从“踩坑”到“填坑”的完整实战经验分享出来，并附上一个用pytest框架组织的、可直接复用的下载测试实战案例。

无论你是做自动化测试的QA工程师，还是需要定时抓取文件的数据工程师，或者是任何被浏览器下载弹窗困扰的开发者，这套方案都能让你彻底解脱。接下来，我们从为什么选择Playwright开始，一步步拆解实现细节。

2. 核心工具选型：为什么是Playwright而非Selenium？

在开始动手之前，我们必须搞清楚工具选型背后的逻辑。为什么在这个场景下，Playwright是比Selenium更优的选择？这不仅仅是“新”与“旧”的问题，而是架构和设计理念的差异。

2.1 Selenium的瓶颈：弹窗处理的“阿喀琉斯之踵”

Selenium通过WebDriver协议与浏览器通信。这个协议设计之初，主要目标是模拟用户对网页内容的操作，比如点击、输入、获取元素等。浏览器原生的“另存为”对话框，是操作系统级别的组件，而非网页DOM的一部分。WebDriver协议无法直接与之交互。这就是问题的根源。

传统的Selenium解决方案通常是：

1. 修改浏览器首选项：在启动浏览器时，通过ChromeOptions设置默认下载路径并禁用下载提示。这招对部分简单场景有效，但存在明显缺陷：
   • 无法获取下载状态：你只知道浏览器“应该”在下载，但不知道它何时开始、何时结束、是否成功。
   • 文件名不可控：下载的文件名通常是服务器返回的原始文件名，如果你想根据页面内容重命名，会非常麻烦。
   • 兼容性问题：不同浏览器（Chrome, Firefox）的设置方式差异很大，且浏览器版本升级可能导致设置失效。
2. 借助第三方工具：集成AutoIt或PyAutoGUI来识别并操作系统弹窗。这是下下策，因为它：
   • 极度脆弱：依赖于固定的窗口标题、按钮坐标。系统主题、分辨率、语言设置的改变都会导致脚本失败。
   • 破坏跨平台性：Windows上的脚本无法在Linux或macOS上运行。
   • 阻塞脚本：操作弹窗时，脚本必须等待，无法进行其他异步任务。

2.2 Playwright的破局之道：原生API支持与事件驱动

Playwright由微软团队开发，它采用了不同的思路。它不仅仅是一个WebDriver客户端，而是直接通过DevTools Protocol等底层协议与浏览器内核对话，提供了更强大、更底层的控制能力。对于文件下载，它提供了原生的、一等公民级别的支持。

其核心优势体现在：

• page.on(‘download’)事件监听器：这是关键。当页面触发下载时（无论是通过点击一个带download属性的链接，还是通过JavaScript触发的文件流），Playwright会抛出一个download事件。你的脚本可以监听这个事件，并立即获取到一个Download对象，完全绕过了系统弹窗。
• Download对象：这个对象包含了下载的所有信息：文件的网络请求URL、建议的文件名、下载状态等。最重要的是，它提供了save_as(path)方法，让你可以自由指定文件保存的完整路径和名称。
• 等待下载完成：Download对象还有path()方法（等待下载完成并返回临时路径）和failure()方法（获取失败原因），让你能精确控制下载流程，判断成功与否。

简单来说，Selenium试图“绕过”或“模拟”弹窗，而Playwright直接从浏览器内核层面“拦截”了下载请求，并提供了编程接口。这是一种降维打击。

注意：Playwright需要安装特定的浏览器版本（它自带一个经过优化的Chromium、Firefox和WebKit）。这看似增加了部署复杂度，但实际上保证了环境的一致性，避免了因用户本地浏览器版本差异导致的问题，对于自动化任务反而是优点。

3. 环境搭建与基础配置

理论说清楚了，我们开始动手。第一步是把环境搭起来。我会以macOS/Linux的命令行示例为主，Windows用户只需将pip3和python3命令替换为pip和python即可。

3.1 安装Playwright Python包

打开你的终端，执行以下命令。建议使用虚拟环境（如venv或conda）来管理依赖，避免包冲突。

# 安装Playwright的Python客户端库 pip3 install playwright # 安装Playwright自带的浏览器（Chromium, Firefox, WebKit）。这一步会下载浏览器，时间稍长。 playwright install

playwright install这个命令非常关键，它会下载Playwright维护的、保证兼容性的浏览器版本。如果你只想安装Chromium以节省空间和時間，可以使用playwright install chromium。

3.2 验证安装与录制工具（可选但推荐）

安装完成后，可以写一个最简单的脚本来验证：

# test_install.py import asyncio from playwright.async_api import async_playwright async def main(): async with async_playwright() as p: # 启动无头Chromium浏览器 browser = await p.chromium.launch(headless=True) page = await browser.new_page() await page.goto('https://example.com') print(await page.title()) await browser.close() asyncio.run(main())

运行python3 test_install.py，如果输出“Example Domain”，说明环境配置成功。

另外，Playwright提供了一个强大的代码生成器，对于初学者快速上手或探索页面操作序列非常有帮助：

# 启动代码生成器，会打开一个有界面的浏览器 playwright codegen https://example.com

这个工具能记录你的点击、输入操作，并实时生成对应的Python代码。虽然我们最终的项目不依赖它，但在分析目标网站下载触发逻辑时，它是一个绝佳的辅助工具。

4. 核心实现：监听、拦截与保存下载文件

现在进入最核心的部分。我们将实现一个完整的、健壮的文件自动下载函数。我会先给出一个基础版本，然后逐步添加错误处理、状态等待等工业级特性。

4.1 基础版本：事件监听与文件保存

假设我们要从一个网站下载文件，这个网站有一个按钮，点击后会触发文件下载。我们的脚本需要：

1. 导航到页面。
2. 点击下载按钮。
3. 拦截下载事件，并将文件保存到指定位置。

import asyncio from pathlib import Path from playwright.async_api import async_playwright, Download async def download_file(url: str, download_selector: str, save_dir: Path): """ 基础版文件下载函数 :param url: 目标网页地址 :param download_selector: 触发下载的按钮/链接的CSS选择器 :param save_dir: 文件保存目录 """ async with async_playwright() as p: # 启动浏览器，设置headless=True为无头模式 browser = await p.chromium.launch(headless=True) # 创建新页面上下文，可以统一设置下载行为 context = await browser.new_context(accept_downloads=True) # 必须设置为True page = await context.new_page() # 用于存储下载对象的Future download_future = asyncio.Future() # 核心：注册下载事件监听器 def on_download(download: Download): # 当下载事件触发时，设置future的结果为这个download对象 if not download_future.done(): download_future.set_result(download) page.on('download', on_download) try: # 导航到目标页面 await page.goto(url) # 点击触发下载的元素 await page.click(download_selector) # 等待下载事件被触发，获取download对象，最多等待30秒 download = await asyncio.wait_for(download_future, timeout=30.0) # 构建保存路径：使用下载的建议文件名，保存在指定目录 suggested_filename = download.suggested_filename if not suggested_filename: suggested_filename = f"downloaded_file_{int(time.time())}" save_path = save_dir / suggested_filename # 将文件保存到指定路径 await download.save_as(save_path) print(f"文件已下载并保存至: {save_path}") # 可选：等待下载在后台完成（save_as内部已包含等待） # download.path() # 这会等待下载完成并返回临时文件路径 except asyncio.TimeoutError: print("错误：在指定时间内未触发下载。") except Exception as e: print(f"下载过程中发生错误: {e}") finally: await browser.close() # 使用示例 async def main(): target_url = "https://example.com/download-page" download_button_selector = "a#download-link" # 替换为实际的选择器 save_directory = Path("./downloads") save_directory.mkdir(parents=True, exist_ok=True) # 确保目录存在 await download_file(target_url, download_button_selector, save_directory) if __name__ == "__main__": asyncio.run(main())

代码解析与注意事项：

1. accept_downloads=True：在创建浏览器上下文(new_context)时，这个参数必须设置为True，否则浏览器会拒绝所有下载，监听器也不会生效。
2. page.on(‘download’, on_download)：这是核心魔法。我们将一个回调函数on_download绑定到页面的download事件上。一旦页面内有下载触发，这个函数就会被调用，并接收到一个已经初始化好的Download对象。
3. asyncio.Future()：由于下载事件是异步触发的，我们使用一个Future对象来“等待”这个事件的发生。这是一种在异步编程中协调不同回调的常见模式。
4. download.suggested_filename：浏览器从服务器响应头（通常是Content-Disposition）中获取的建议文件名。强烈建议优先使用这个名称，因为它通常是最准确的。如果为空，则需要自己生成一个。
5. download.save_as(path)：该方法执行两个操作：a) 等待下载数据完全传输完毕；b) 将文件移动到你指定的path。这是一个阻塞（异步等待）操作，所以你不必再额外调用download.path()来等待完成。

4.2 进阶版本：添加状态检查、重命名与超时控制

基础版本能工作，但不够健壮。在实际项目中，我们需要考虑：下载可能失败（网络错误、服务器返回404）、我们需要根据页面内容自定义文件名、需要更精细的超时控制。

import asyncio import time from pathlib import Path from typing import Optional from playwright.async_api import async_playwright, Download, Page, TimeoutError as PlaywrightTimeoutError async def robust_download( page: Page, trigger_action: callable, # 一个执行触发下载操作的异步函数 save_dir: Path, custom_filename: Optional[str] = None, download_timeout: float = 120.0, action_timeout: float = 30.0 ) -> Optional[Path]: """ 健壮版下载函数 :param page: 已创建的Playwright页面对象 :param trigger_action: 异步函数，执行触发下载的操作（如 page.click()） :param save_dir: 保存目录 :param custom_filename: 自定义文件名（不含路径），若为None则使用建议文件名 :param download_timeout: 下载过程总超时（秒） :param action_timeout: 触发操作后的等待超时（秒） :return: 成功则返回保存的Path对象，失败返回None """ download_future = asyncio.Future() def on_download(download: Download): if not download_future.done(): download_future.set_result(download) # 注册监听器 page.on('download', on_download) try: # 执行用户定义的触发操作 await trigger_action() # 等待下载事件被触发 download: Download = await asyncio.wait_for(download_future, timeout=action_timeout) print(f"下载已开始，建议文件名: {download.suggested_filename}") # 确定最终文件名 if custom_filename: final_filename = custom_filename else: final_filename = download.suggested_filename or f"download_{int(time.time())}" save_path = save_dir / final_filename # 保存文件，并设置下载过程超时 await asyncio.wait_for(download.save_as(save_path), timeout=download_timeout) print(f"文件下载成功: {save_path}") # 检查下载是否真的成功（例如，服务器可能返回错误页面而不是文件） if download.failure(): print(f"下载失败，原因: {download.failure()}") save_path.unlink(missing_ok=True) # 删除可能已存在的损坏文件 return None # 验证文件是否确实存在且大小不为0（可选） if save_path.exists() and save_path.stat().st_size > 0: return save_path else: print("错误：下载的文件为空或不存在。") return None except asyncio.TimeoutError: print(f"错误：操作或下载在{action_timeout}/{download_timeout}秒内未完成。") return None except Exception as e: print(f"下载过程中发生未预期错误: {e}") return None finally: # 重要：移除事件监听器，避免影响后续操作或内存泄漏 page.remove_listener('download', on_download) # 使用示例 async def main_advanced(): async with async_playwright() as p: browser = await p.chromium.launch(headless=True) context = await browser.new_context(accept_downloads=True) page = await context.new_page() await page.goto('https://httpbin.org/response-headers?Content-Disposition=attachment%3B%20filename%3D%22example.json%22') save_dir = Path('./advanced_downloads') save_dir.mkdir(exist_ok=True) # 定义一个触发动作：点击一个按钮（这里用goto模拟，实际可能是click） async def trigger_dl(): # 假设页面上有一个按钮，其id是'download-btn' # await page.click('#download-btn') # 由于httpbin示例直接返回文件，我们直接触发，这里用重新加载模拟 pass # 在这个特定例子中，导航即触发 # 调用健壮下载函数，并尝试自定义文件名 saved_file_path = await robust_download( page=page, trigger_action=trigger_dl, save_dir=save_dir, custom_filename="my_custom_data.json", # 覆盖服务器建议的文件名 download_timeout=60, action_timeout=10 ) if saved_file_path: print(f"文件最终保存于: {saved_file_path}") else: print("下载失败。") await browser.close()

这个进阶版本的提升点：

1. 参数化触发动作：将trigger_action抽象为一个可调用对象，使得函数更加通用。你可以传入任何异步函数，比如先填写表单再点击，或者等待某个条件后再触发。
2. 双重超时控制：action_timeout控制从触发操作到下载事件发生的时间；download_timeout控制整个文件数据传输和保存的时间。这对于下载大文件非常有用。
3. 失败检查：调用download.failure()来检查下载过程是否在网络层面失败（如连接中断）。这是Playwright提供的原生状态检查。
4. 文件验证：下载完成后，检查文件是否存在以及文件大小，防止下载到空的或损坏的文件（例如服务器返回了一个错误HTML页面，但状态码是200）。
5. 清理监听器：在finally块中使用page.remove_listener移除事件监听。这是一个好习惯，能避免在长时间运行的脚本中，监听器累积导致的内存泄漏或意外行为。
6. 自定义文件名逻辑：提供了灵活的命名策略，优先使用自定义名，其次用服务器建议名，最后用时间戳兜底。

5. 实战：集成pytest构建可复用的下载测试套件

单元测试是保证自动化脚本长期稳定运行的关键。我们将使用pytest框架，把下载功能封装成易于测试的组件。这里会展示如何组织测试用例、使用fixture管理浏览器生命周期，以及如何处理异步测试。

5.1 项目结构规划

一个清晰的项目结构有助于维护。建议如下：

playwright_download_project/ ├── conftest.py # pytest全局配置和fixture定义 ├── downloader/ # 核心功能模块 │ ├── __init__.py │ └── core.py # 包含 robust_download 等核心函数 ├── tests/ # 测试目录 │ ├── __init__.py │ ├── conftest.py # 测试专用的fixture（可选） │ ├── test_basic_download.py │ └── test_advanced_scenarios.py ├── requirements.txt # 项目依赖 └── downloads/ # 默认下载目录（.gitignore忽略）

5.2 创建核心功能模块与全局Fixture

首先，将我们之前写好的健壮下载函数放到downloader/core.py中。

然后，创建顶层的conftest.py，用于定义pytest fixture，管理Playwright浏览器实例。这是pytest的魔法文件，其中的fixture可以被所有测试文件使用。

# conftest.py import pytest import asyncio from pathlib import Path from playwright.async_api import async_playwright, Browser, BrowserContext, Page # 定义一个事件循环fixture，用于运行异步测试 @pytest.fixture(scope="session") def event_loop(): """为整个测试会话创建一个事件循环。""" loop = asyncio.get_event_loop_policy().new_event_loop() yield loop loop.close() # 浏览器实例fixture，会话级别，所有测试共用（节省启动时间） @pytest.fixture(scope="session") async def browser(event_loop): async with async_playwright() as p: # 启动浏览器，可根据环境变量决定是否无头 headless = True # 测试环境通常为无头 browser = await p.chromium.launch(headless=headless, slow_mo=100) # slow_mo让操作变慢，便于观察 yield browser # 测试结束后关闭浏览器 await browser.close() # 浏览器上下文fixture，函数级别，每个测试独立，避免状态污染 @pytest.fixture async def browser_context(browser): context = await browser.new_context(accept_downloads=True) yield context await context.close() # 页面fixture，函数级别，每个测试获得一个干净的页面 @pytest.fixture async def page(browser_context): page = await browser_context.new_page() yield page await page.close() # 临时下载目录fixture，函数级别，每个测试有自己的干净目录 @pytest.fixture def temp_download_dir(tmp_path): download_dir = tmp_path / "test_downloads" download_dir.mkdir() return download_dir

Fixture设计解析：

• event_loop:pytest-asyncio插件需要这个fixture来运行异步测试函数。我们创建了一个会话级别的事件循环。
• browser:会话级别(scope="session”)。启动和关闭浏览器开销很大，让所有测试用例共享同一个浏览器实例可以极大提升测试速度。
• browser_context:函数级别(scope=”function”, 默认)。每个测试用例获得一个独立的上下文，这相当于一个独立的“隐身会话”，拥有独立的cookie、本地存储和下载设置。这确保了测试之间的隔离性，一个测试的下载不会影响另一个。
• page:函数级别。每个测试用例获得一个来自其独立上下文的新页面，保证页面状态干净。
• temp_download_dir:函数级别。使用pytest内置的tmp_pathfixture，为每个测试创建一个唯一的临时目录来存放下载文件。测试结束后，该目录会被自动清理，确保没有残留文件影响下一次测试。

5.3 编写具体的测试用例

现在，我们来编写测试文件。我们测试两种常见场景：1) 直接下载一个已知的文件；2) 在一个需要交互的页面上触发下载。

# tests/test_basic_download.py import pytest from pathlib import Path from downloader.core import robust_download @pytest.mark.asyncio async def test_download_from_static_link(page, temp_download_dir): """ 测试场景：页面有一个直接指向文件的链接，点击即下载。 使用 httpbin.org 的 /stream-bytes 端点模拟文件下载。 """ # 导航到一个能触发下载的测试页面 # 这里我们使用 httpbin，它返回一个包含特定字节流的“文件” await page.goto('https://httpbin.org/stream-bytes/1024?seed=test') # 定义触发动作：在这个简单例子中，导航本身就会触发下载（因为httpbin返回的是流） # 但在真实场景中，可能是点击一个链接。我们这里模拟点击一个不存在的元素来“触发”下载事件。 # 实际上，对于httpbin /stream-bytes，访问URL就会开始下载。 # 我们需要先设置监听器，再执行导航。但 robust_download 要求先有page对象。 # 因此，更合理的测试是使用一个真正需要点击的页面。我们换一个端点。 await page.goto('about:blank') # 先清空页面 # 使用一个能通过点击触发下载的测试URL（例如，一个设置了下行头 attachment 的端点） # 我们通过 evaluate 在页面注入一个下载链接并点击它 download_url = 'https://httpbin.org/response-headers?Content-Disposition=attachment%3B%20filename%3D%22testfile.bin%22&Content-Type=application%2Foctet-stream' await page.evaluate(f"""() => {{ const link = document.createElement('a'); link.href = '{download_url}'; link.download = 'testfile.bin'; link.textContent = 'Download Test File'; document.body.appendChild(link); link.click(); }}""") async def trigger_action(): # 上面的 evaluate 已经执行了点击，所以这里不需要再做任何事。 # 这个函数的存在是为了满足 robust_download 的接口。 pass saved_path = await robust_download( page=page, trigger_action=trigger_action, save_dir=temp_download_dir, custom_filename="httpbin_test_file.bin" ) # 断言：文件应该被成功下载并保存 assert saved_path is not None assert saved_path.exists() # 检查文件大小（httpbin返回的流大小是随机的，但我们知道它不为空） assert saved_path.stat().st_size > 0 # 检查文件名是否符合我们的自定义 assert saved_path.name == "httpbin_test_file.bin" @pytest.mark.asyncio async def test_download_with_form_submission(page, temp_download_dir): """ 测试场景：需要先填写表单，提交后生成并下载文件。 这里用一个模拟的本地HTML文件来演示。 """ # 创建一个临时的HTML表单页面，提交后会触发文件下载 # 由于安全限制，真实的文件下载需要服务器配合。这里我们简化，用一段JavaScript模拟下载行为。 html_content = """ <!DOCTYPE html> <html> <body> <form id="downloadForm"> <input type="text" name="data" value="Sample Data"> <button type="submit">Generate Report</button> </form> <script> document.getElementById('downloadForm').addEventListener('submit', function(e) { e.preventDefault(); // 模拟创建一个Blob并触发下载 const blob = new Blob(['This is the report content for: ' + this.data.value], {type: 'text/plain'}); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'report_' + Date.now() + '.txt'; document.body.appendChild(a); a.click(); document.body.removeChild(a); URL.revokeObjectURL(url); }); </script> </body> </html> """ # 将HTML内容设置到当前页面 await page.set_content(html_content) async def trigger_action(): # 触发动作：点击提交按钮 await page.click('button[type="submit"]') saved_path = await robust_download( page=page, trigger_action=trigger_action, save_dir=temp_download_dir, download_timeout=5.0 ) assert saved_path is not None assert saved_path.exists() # 检查文件内容是否包含我们提交的数据 file_content = saved_path.read_text() assert "Sample Data" in file_content @pytest.mark.asyncio async def test_download_timeout_handling(page, temp_download_dir): """ 测试异常场景：下载超时或未触发。 """ await page.goto('about:blank') async def trigger_action_that_never_downloads(): # 一个永远不会触发下载的动作，比如点击一个普通链接 await page.evaluate("""() => { const link = document.createElement('a'); link.href = 'https://example.com'; link.textContent = 'Go to Example'; document.body.appendChild(link); link.click(); }""") saved_path = await robust_download( page=page, trigger_action=trigger_action_that_never_downloads, save_dir=temp_download_dir, action_timeout=2.0, # 设置很短的超时，期望它超时 download_timeout=2.0 ) # 断言：由于没有下载触发， robust_download 应该返回 None assert saved_path is None # 断言下载目录是空的（或者只有我们可能创建的占位文件，但不应有目标文件） # 注意：由于触发动作可能导航到其他页面，可能会产生其他下载，这个断言在复杂场景下可能不稳定。 # 更稳定的做法是检查特定文件名不存在。 # assert len(list(temp_download_dir.iterdir())) == 0

测试要点与技巧：

1. @pytest.mark.asyncio：这个装饰器是必须的，它告诉pytest这个测试函数是异步的，需要用asyncio事件循环来运行。
2. 使用依赖注入：测试函数通过参数声明它需要的fixture（如page,temp_download_dir），pytest会自动注入。这使得测试代码非常干净，且易于复用fixture提供的资源。
3. 测试用例隔离：得益于browser_context和pagefixture的函数级别作用域，每个测试都在一个全新的浏览器上下文和页面中运行，互不干扰。
4. 测试正面与负面场景：我们不仅测试了正常的下载流程(test_download_from_static_link,test_download_with_form_submission)，还测试了异常情况(test_download_timeout_handling)，确保我们的robust_download函数在出错时行为符合预期。
5. 模拟与真实：在测试中，我们混合使用了真实的网络服务（httpbin.org）和客户端模拟（page.set_content）。对于核心逻辑的单元测试，应尽量使用可控的模拟；对于集成测试，则使用真实的测试环境。

5.4 运行测试与查看报告

在项目根目录下，运行以下命令：

# 运行所有测试 pytest -v # 运行特定测试文件 pytest tests/test_basic_download.py -v # 运行并生成HTML报告（需要安装 pytest-html） pytest --html=report.html --self-contained-html

-v参数会输出更详细的信息，方便查看每个测试用例的执行情况。如果测试失败，pytest会给出清晰的错误回溯，帮助你快速定位问题。

6. 常见问题排查与实战心得

在实际使用Playwright进行自动化下载的过程中，你肯定会遇到一些坑。下面是我总结的一些典型问题及其解决方案，以及一些从实战中得来的经验技巧。

6.1 下载监听器不触发

问题现象：点击了下载按钮，但page.on(‘download’)事件监听器里的回调函数从未被调用。

可能原因与排查步骤：

1. accept_downloads未设置或为False：这是最常见的原因。确保在创建浏览器上下文(browser.new_context)时，传入了accept_downloads=True。注意：这个设置是上下文级别的，不是页面级别的。
2. 下载被浏览器拦截或由新窗口/tab处理：有些下载链接设置了target=”_blank”，或者网站逻辑是在新窗口中开始下载。Playwright的page对象只监听当前页面的下载事件。你需要：
   • 监听整个上下文的下载：使用context.on(‘download’, …)而不是page.on(‘download’, …)。这样，该上下文下所有页面的下载都会被捕获。

   async with async_playwright() as p: browser = await p.chromium.launch() context = await browser.new_context(accept_downloads=True) download_future = asyncio.Future() def handle_download(download): if not download_future.done(): download_future.set_result(download) context.on('download', handle_download) # 监听上下文 page = await context.new_page() # ... 你的操作

   • 等待新页面并监听它：如果下载确实在新标签页触发，你需要使用page.wait_for_event(‘popup’)来等待新页面，然后在新页面上设置监听器。
3. 点击操作未正确触发下载：可能元素不是真正的下载链接（例如，是通过JavaScript异步请求文件）。使用Playwright的代码生成器(playwright codegen)重新录制一遍操作，确认点击的选择器和步骤是否正确。有时可能需要等待某个元素出现或网络请求完成后再点击。
4. 浏览器或网站使用了不同的下载机制：极少数情况下，网站可能通过iframe、Worker或其他非常规方式触发下载。这时需要更仔细地分析网络请求。打开浏览器的开发者工具（在Playwright中可以通过await page.pause()暂停脚本，然后手动操作），在Network标签页查看点击下载按钮时，产生了什么类型的请求（通常是带有Content-Disposition: attachment头的请求）。

6.2 下载的文件损坏或为空

问题现象：文件成功保存，但打开时是空的，或者内容不是预期的二进制文件（可能是HTML错误页面）。

解决方案：

1. 检查download.failure()：在调用save_as之后，立即检查download.failure()的返回值。如果不为None，则说明下载过程本身失败了（如网络错误、服务器返回4xx/5xx状态码）。
2. 验证文件头和大小：即使failure()为None，服务器也可能返回一个状态码为200的错误页面。在保存后，可以读取文件的前几个字节或检查文件大小。

   saved_path = await download.save_as(‘file.zip’) if saved_path.stat().st_size < 1024: # 假设文件至少1KB print(“警告：下载的文件可能过小或为空。”) # 可以读取前500字节检查是否是文本/HTML with open(saved_path, ‘rb’) as f: header = f.read(500) if b’<html’ in header.lower() or b’error’ in header.lower(): print(“文件内容疑似错误页面。”)

3. 等待下载真正完成：download.save_as()方法内部会等待下载完成。但如果你在调用它之前就关闭了浏览器上下文或页面，下载可能会中断。确保你的脚本逻辑在save_as完成前，保持相关的page和context处于打开状态。

6.3 异步编程中的竞态条件

问题现象：偶尔会错过下载事件，或者Future对象已经被设置过了。

根本原因：在异步环境中，事件触发和代码执行顺序是不确定的。如果下载在注册监听器之前就触发了，或者同一个页面短时间内触发了多次下载，我们的简单Future模式可能会出错。

健壮化方案：使用队列（asyncio.Queue）

对于可能连续触发多个下载的场景，使用asyncio.Queue是更安全的选择。

import asyncio from asyncio import Queue from playwright.async_api import Page, Download async def handle_multiple_downloads(page: Page, save_dir: Path): """处理一个页面内可能发生的多次下载。""" download_queue = Queue() def on_download(download: Download): # 将每个下载对象放入队列 download_queue.put_nowait(download) page.on(‘download’, on_download) # ... 执行会触发下载的操作 ... # 在一个循环中处理队列中的所有下载 saved_paths = [] try: while True: # 设置一个超时，避免无限等待 download = await asyncio.wait_for(download_queue.get(), timeout=10.0) filename = download.suggested_filename or f”download_{len(saved_paths)}.bin” save_path = save_dir / filename await download.save_as(save_path) saved_paths.append(save_path) print(f”已处理下载: {filename}”) download_queue.task_done() # 通知队列任务完成 except asyncio.TimeoutError: print(“等待新下载超时，可能所有下载已完成。”) finally: page.remove_listener(‘download’, on_download) return saved_paths

6.4 实战心得与技巧

1. 优先使用browser.new_context管理状态：每个测试或任务都应该在独立的context中运行。这不仅能隔离下载，还能隔离cookies、localStorage等，使脚本行为更可预测，也更容易实现并行执行。
2. 利用slow_mo参数调试：在浏览器启动时设置slow_mo=500（单位毫秒），会让Playwright的每个操作都放慢。这在调试复杂的交互流程时非常有用，你可以清楚地看到页面是如何一步步变化的。
3. 结合page.wait_for_event进行更精细的控制：除了监听download事件，你还可以等待其他事件，比如request或response，来精确判断下载请求何时发出、何时完成。

   async with page.expect_download() as download_info: await page.click(‘#download-button’) download = await download_info.value # 这种方式更简洁，适用于你知道点击后必然触发一次下载的场景

4. 处理需要认证的下载：如果下载链接需要登录，务必在同一个context内完成登录操作，以保持会话状态。Playwright可以很方便地保存和加载登录状态（context.storage_state()）。
5. 无头模式下的资源节省：对于生产环境的定时任务，务必使用headless=True。你还可以通过args参数传递更多Chromium启动参数来优化资源占用，例如--disable-gpu,--no-sandbox（注意安全考量），--single-process等。