browser-use 入门完整指南：AI 自动下载网页文件，一句话跑通批量归档-开发者社区

browser-use 入门完整指南：AI 自动下载网页文件，一句话跑通批量归档

【免费下载链接】browser-useAgents that use the browser.项目地址: https://gitcode.com/GitHub_Trending/br/browser-use

月底结算，120 份物流 PDF 要逐份点开、右键、另存为，光下载就耗掉你半天。browser-use 是让 AI 直接操作浏览器、自动完成"浏览→下载→归档"全链路的开源框架：你用一句话描述任务，它自己打开网页、找到下载链接、保存文件，全程不用碰鼠标。这篇 browser-use 教程带你从安装到跑通第一个任务。

先看效果：一句话需求，变成目录里的文件

它的输入输出非常直白：

你说的话（输入）	AI 做的	你得到的（输出）
"下载这两个站点上最小的文档文件"	打开页面→读页面→点链接→等下载完成→再点下一个	文件已躺在你指定的目录里，随时可取

整个过程它像真人一样操作：先"看"一眼页面，判断哪个链接才是目标文件，点击后等待下载完成，再回到列表处理下一个。你唯一的参与，是把需求说明白。

上图就是 AI 在真实浏览器里打开并操作过的页面。它能处理的远不止下载页，表单、商城、后台系统都能操作。

能力边界：browser-use 能做什么，别指望什么

它能稳做的	别指望它做的
按文字描述定位下载链接并触发下载（PDF、DOC、CSV、ZIP 都常见）	绕过验证码、风控等反爬拦截
文件直接落进你指定的目录，目录结构由它规划	通过需要人工扫码的强认证流程
下载后自动重命名、分类，还能接后续处理	在完全无网的离线环境里工作
多站点、批量、定时重复跑同一套任务	一次运行处理需要人工判断的灰色边界

它接管一切"人看一眼就知道怎么点"的操作；人也要摸索半天的坑，它同样会卡住。

上手指南：十分钟装好，跑通第一次 AI 自动下载

环境要求不高：Python 3.11 以上，加一个 LLM 的 API Key（下例用 Google Gemini）。

git clone https://gitcode.com/GitHub_Trending/br/browser-use cd browser-use pip install browser-use

这是最小可运行示例，全文就两段代码，另一段在上面：

import asyncio import os from browser_use import Agent, Browser, ChatGoogle # 大模型：换成你自己的 API Key llm = ChatGoogle(model='gemini-2.5-flash', api_key=os.getenv('GOOGLE_API_KEY')) # 指定下载目录，AI 会把文件存到这里 browser = Browser(downloads_path='~/Downloads/auto_downloads') async def main(): agent = Agent( task='访问 https://file-examples.com/ ，下载最小的 DOC 文件，' '然后回到列表继续下载最小的 XLS 文件', llm=llm, browser=browser, ) await agent.run(max_steps=25) # 最多跑 25 步，防止失控 if __name__ == '__main__': asyncio.run(main())

运行前检查两件事：模型的 API Key 环境变量已设置、下载目录有写权限。这两点是新手翻车最多的地方。

跑起来后你会看到：浏览器自动打开→AI 读页面→点中 DOC 链接→等下载完成→回到列表→再点 XLS 链接。两个文件落进auto_downloads目录，单步耗时取决于模型响应速度，全程不用你干预。

原理拆解：AI 是怎么"看懂"网页的

它并不"看"网页，处理的是文本和截图。browser-use 把这拆成三个角色：

菜单。浏览器扩展browser_use/dom/serializer/把当前页面的按钮、链接、输入框序列化成一份带编号的可点击清单，喂给 AI。就像餐厅菜单：每道菜有编号，AI 只要说"来 37 号"。它不写死任何网站的规则，而是每次现读现理解——这是它能"看懂"陌生网站的根本原因。
服务员。browser_use/agent/service.py里的 Agent 接到编号后真正动手：点击、填表、滚动、翻页，每一步都记进执行历史，出错还能回看纠正。
质检员。下载从点击到落盘中间有跳转、有进度，browser_use/browser/watchdogs/downloads_watchdog.py全程盯着开始、进度、完成三个事件，网络抖动导致文件没下全时自动重试。

另外，browser_use/browser/profile.py的 BrowserProfile 可以预设下载目录、登录态等参数，是进阶配置的主入口。

进阶玩法：三个高频 AI 浏览器自动化场景

物流运营归档。任务："去承运商后台把上月的运单 PDF 逐份下载，按'运单/2026-08'存好。"它替你登录、翻页、逐个下载、落目录，原来半天的活趁你喝咖啡就做完了。
电商规格表收集。任务："去某品牌官网，把全线产品的规格表 PDF 存到'规格/产品线'文件夹。"它替你逐个逛产品页、下载、按文件夹归类，你只负责验收。
HR 岗位资料收集。任务："把招聘站上每个岗位的职位描述 PDF 按职能分类下载。"它替你翻站、下载、命名归档，后续改 JD 直接查文件夹。

细节写法可以参考 examples/ 目录里的下载与文件系统示例。

避坑指南：新手最常踩的三个坑

症状	原因	解法
文件"消失"了，哪里都找不到	没传`downloads_path`，文件去了系统临时目录的随机文件夹	先指定下载目录再跑任务，这是第一课
AI 在登录页反复打转	站点需要登录，任务里没有会话	先用 examples/browser/save_cookies.py 手动保存一次 Cookie/存储状态，再传给任务复用
找不到下载按钮，乱点半天	任务描述太含糊	描述里带上筛选条件、文件格式、保存规则，比如"下载报价单区域最新的 PDF，按供应商名命名"
跑几步弹出验证码卡死	站点风控拦截	换更强的模型重试，或改到风控宽松的时间段跑