Crawl4AI 基于身份的爬虫实战持久化浏览器配置、BrowserProfiler 与区域地理信息定制【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai本文聚焦 Crawl4AI 的 Identity-Based Crawling基于身份的爬虫能力通过持久化浏览器配置Managed Browsers复用真实的登录态、Cookie 与浏览器指纹让你以“本人身份”访问需要登录或个性化配置的站点同时讲解 Magic Mode 轻量自动化的定位与差异以及locale/timezone_id/geolocation三项身份维度配置。读完后你可以掌握三种创建持久化配置目录的方法、BrowserProfiler的完整 API以及如何组装一个带身份与地理信息的一致化爬取流程。官方教程原文见 identity-based-crawling.md。1. 两种方案总览Managed Browsers 与 Magic ModeCrawl4AI 提供两条让爬虫“看起来像真人”的路径二者定位完全不同Managed Browsers托管浏览器推荐创建并复用持久化浏览器配置persistent profile。配置目录中保存 localStorage、Cookie 和各类会话数据爬虫运行时可以以“真实用户”的身份浏览——带上你的登录态、偏好与 Cookie。Magic Mode魔法模式一种简化版自动化。不保存任何长期数据仅在本次运行中模拟类人浏览行为适合作为快速原型或临时任务的兜底方案。Managed Browsers 的核心收益真实的浏览体验会话数据与浏览器指纹得以保留站点将其视为普通用户一次配置重复使用在指定的数据目录中完成一次登录或验证码之后后续爬取无需重复这些步骤数据可达性只要你在自己的浏览器中能看到这些数据就可以用自己的真实身份自动化地获取它们。2. 创建 User Data 目录的三种方式身份爬取的第一步是拥有一个包含登录态的user-data目录。Crawl4AI 提供三种创建途径可按需选择。2.1 命令行方式直接用 Playwright 的 Chromium 二进制安装了 Crawl4AI 之后系统内已存在 Playwright 管理的 Chromium。可以从命令行手动启动它并指定自定义数据目录定位 Chromium 二进制大多数系统上Playwright 安装的浏览器位于~/.cache/ms-playwright/或类似路径。可运行以下命令查看概览python -m playwright install --dry-run # 或 playwright install --dry-run例如在 Linux 上你会看到类似这样的路径~/.cache/ms-playwright/chromium-1234/chrome-linux/chrome用--user-data-dir启动# Linux 示例 ~/.cache/ms-playwright/chromium-1234/chrome-linux/chrome \ --user-data-dir/home/you/my_chrome_profile# macOS 示例Playwright 内置二进制 ~/Library/Caches/ms-playwright/chromium-1234/chrome-mac/Chromium.app/Contents/MacOS/Chromium \ --user-data-dir/Users/you/my_chrome_profile# Windows 示例PowerShell/cmd C:\Users\you\AppData\Local\ms-playwright\chromium-1234\chrome-win\chrome.exe ^ --user-data-dirC:\Users\you\my_chrome_profile路径请以你本机ms-playwright缓存结构中的实际子目录为准。浏览器打开后登录各站点、完成所需配置然后关闭——配置数据即保存在该文件夹中。将该目录交给BrowserConfig.user_data_dirfrom crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig browser_config BrowserConfig( headlessTrue, use_managed_browserTrue, user_data_dir/home/you/my_chrome_profile, browser_typechromium )再次运行代码时Crawl4AI 会复用该目录保留会话数据、Cookie、localStorage 等。从源码看这条路径最终与 Crawl4AI 内部机制是同一套参数browser_manager.py 中ManagedBrowser._get_browser_args()启动 Chromium 时正是拼接--remote-debugging-portport、--user-data-dirdir无头模式追加--headlessnew。也就是说命令行手动启动与框架托管启动在参数层面完全一致你手工登录产生的数据可被框架无缝接管。2.2 使用 Crawl4AI CLI最省心如果偏好交互式引导可以直接使用内置 CLI 的 profile 管理命令启动 profile 管理器crwl profiles选择 Create new profile输入 profile 名称。此时会打开一个 Chromium 窗口供你登录站点、设置偏好完成后回到终端按q保存 profile。Profile 保存在~/.crawl4ai/profiles/profile_name例如/home/you/.crawl4ai/profiles/test_profile_1目录内会额外生成一份storage_state.json用于持久化 Cookie 与会话数据。可选择 List profiles 查看已有 profile 及其路径。将保存的路径交给BrowserConfig.user_data_dirfrom crawl4ai import AsyncWebCrawler, BrowserConfig profile_path /home/you/.crawl4ai/profiles/test_profile_1 browser_config BrowserConfig( headlessTrue, use_managed_browserTrue, user_data_dirprofile_path, browser_typechromium, ) async with AsyncWebCrawler(configbrowser_config) as crawler: result await crawler.arun(urlhttps://example.com/private)CLI 还支持列出、删除 profile甚至直接从菜单中选取 profile 试爬一个 URL。对应实现位于 cli.pymanage_profiles()菜单、display_profiles_table()列表展示、create_profile_interactive()交互式创建和delete_profile_interactive()删除流程全部委托给BrowserProfiler执行。2.3 使用 BrowserProfiler 类程序化程序化场景下直接调用BrowserProfiler即可详见第 4 节。三种方式的本质相同产出一个带登录态的user_data_dir之后交给BrowserConfig复用。3. 在 Crawl4AI 中使用 Managed Browsers拿到带会话数据的目录后将其传入BrowserConfig即可。完整示例import asyncio from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig async def main(): # 1) 引用你的持久化数据目录 browser_config BrowserConfig( headlessTrue, # True for automated runs verboseTrue, use_managed_browserTrue, # Enables persistent browser strategy browser_typechromium, user_data_dir/path/to/my-chrome-profile ) # 2) 标准爬取配置 crawl_config CrawlerRunConfig( wait_forcss:.logged-in-content ) async with AsyncWebCrawler(configbrowser_config) as crawler: result await crawler.arun(urlhttps://example.com/private, configcrawl_config) if result.success: print(Successfully accessed private data with your identity!) else: print(Error:, result.error_message) if __name__ __main__: asyncio.run(main())3.1 标准工作流外部登录通过 CLI 或--user-data-dir...启动的普通浏览器完成登录关闭该浏览器在 Crawl4AI 中将同一目录传给user_data_dir执行爬取站点看到的身份与刚才登录的用户完全一致。3.2 参数语义源码级说明BrowserConfig中与身份爬取直接相关的参数定义于 async_configs.pyuse_managed_browser默认False启用托管浏览器策略即由ManagedBrowser启动一个独立进程并通过 CDP 接管这是启用持久化配置的前提user_data_dir默认None持久化会话的数据目录。从源码结构看若不提供该参数ManagedBrowser.start()会调用tempfile.mkdtemp(prefixbrowser-profile-)创建临时目录并在cleanup()时删除——这意味着不给user_data_dir的每次运行都是“无记忆”的use_persistent_context默认False设置后会自动置位use_managed_browserTruechannel/chrome_channel默认chromium可选chrome、msedge等渠道list_profiles()的 profile 类型识别逻辑与browser_type一致支持 chromium / firefox。另外注意一个源码细节ManagedBrowser.start()在启动前会做一次“预清理”——终止占用同一调试端口/profile 的旧 Chromium 实例并删除 profile 目录下的SingletonLock、SingletonSocket、SingletonCookie文件避免 Chromium 以“Opening in existing browser session”拒绝启动。这解释了为何同一 profile 不能在两个地方同时打开也说明 Crawl4AI 对“profile 被占用”这一常见坑做了自动处理。4. BrowserProfilerProfile 全生命周期管理Crawl4AI 提供专门的BrowserProfiler类browser_profiler.py来管理浏览器 profile支持创建、列出、删除与获取路径默认存储目录为~/.crawl4ai/profiles/。4.1 创建与管理 Profileimport asyncio from crawl4ai import BrowserProfiler async def manage_profiles(): # 创建 profiler 实例 profiler BrowserProfiler() # 交互式创建 profile - 会打开一个浏览器窗口 profile_path await profiler.create_profile( profile_namemy-login-profile # 可选为 profile 命名 ) print(fProfile saved at: {profile_path}) # 列出所有可用 profile profiles profiler.list_profiles() for profile in profiles: print(fProfile: {profile[name]}) print(f Path: {profile[path]}) print(f Created: {profile[created]}) print(f Browser type: {profile[type]}) # 按名称获取某个 profile 的完整路径 specific_profile profiler.get_profile_path(my-login-profile) # 不再需要时删除 profile success profiler.delete_profile(old-profile-name) asyncio.run(manage_profiles())create_profile的工作流程打开一个浏览器窗口供你操作登录网站、设置偏好等完成后在终端按q关闭浏览器Profile 保存到 Crawl4AI 的 profiles 目录可直接用于BrowserConfig.user_data_dir。从源码看create_profile()有两个值得了解的设计决策可移植性参数创建 profile 时会自动附加--password-storebasicLinux 下使用 basic 存储而非 gnome-keyring与--use-mock-keychainmacOS 下使用 mock keychain。源码注释明确说明Chrome 默认会用操作系统密钥环加密 Cookie导致 profile 无法在机器间迁移这两个参数保证 profile 可以从本地复制到云端服务器复用。storage_state.json 落盘时机用户按q或浏览器进程退出之后、关闭浏览器之前BrowserProfiler会通过 Playwright 的context.storage_state(path...)将 Cookie 与会话序列化为 profile 目录下的storage_state.json——这是 Playwright 的便携 Cookie 格式未加密也是 profile 跨机器可用的关键。此外create_profile接受shrink_level参数可在创建完成后按档位压缩 profile见 4.2。跨平台的q键监听在 Windows 下使用msvcrt.kbhit()在 Unix 下使用termios/tty/select的 cbreak 模式非终端环境则回退到线程化input()模式。4.2 Profile 压缩Shrink真实浏览产生的 profile 会累积大量缓存与历史数据。BrowserProfiler.shrink()提供五级ShrinkLevel定义于 browser_profiler.py 顶部档位保留内容NONE保留一切默认LIGHT仅删缓存保留历史、书签、favicon 等MEDIUM缓存 历史/书签AGGRESSIVE仅保留鉴权数据源码注释标记为推荐MINIMAL仅 Cookie localStorage所有档位都会强制保留storage_state.json因为它对跨机器 profile 移植是必需的。压缩逻辑会先探测Default/子目录Chrome profile 数据通常在其中按KEEP_PATTERNS白名单逐项保留或删除并返回包含removed、kept、bytes_freed、size_before、size_after的报告dry_runTrue时只预览不删除。该能力有对应测试 test_profile_shrink.py。4.3 交互式管理控制台BrowserProfiler还提供一个交互式管理控制台引导你完成创建、列表、删除操作import asyncio from crawl4ai import BrowserProfiler, AsyncWebCrawler, BrowserConfig # 定义一个使用 profile 爬取的函数 async def crawl_with_profile(profile_path, url): browser_config BrowserConfig( headlessTrue, use_managed_browserTrue, user_data_dirprofile_path ) async with AsyncWebCrawler(configbrowser_config) as crawler: result await crawler.arun(url) return result async def main(): profiler BrowserProfiler() # 启动交互式 profile 管理器 # 传入 crawl 回调后菜单会多出使用该 profile 爬取选项 await profiler.interactive_manager(crawl_callbackcrawl_with_profile) asyncio.run(main())interactive_manager(crawl_callback)的菜单为1. 创建新 profile回车可自动生成时间戳命名2. 列出 profile3. 删除 profile带二次确认4/5. 当传入了crawl_callback时多出“选一个 profile 输入 URL 立即爬取”的选项回调以(profile_path, url)调用。4.4 旧接口兼容出于向后兼容ManagedBrowser上原有的静态方法仍然可用但内部全部委托给BrowserProfiler见 browser_manager.py 中create_profile/list_profiles/delete_profile的文档字符串from crawl4ai.browser_manager import ManagedBrowser # 这些方法仍然有效但内部使用 BrowserProfiler profiles ManagedBrowser.list_profiles()4.5 完整示例与相关测试完整的使用示例见 identity_based_browsing.py演示了创建 profile 并使用其进行认证浏览的端到端流程。相关测试用例包括 test_create_profile.py、test_profiles.py 与 test_profile_shrink.py可作为行为基准参考。5. Magic Mode无持久化的轻量自动化如果你不需要持久化 profile 或身份化方案Magic Mode 提供了快速模拟类人浏览的方式不存储任何长期数据from crawl4ai import AsyncWebCrawler, CrawlerRunConfig async with AsyncWebCrawler() as crawler: result await crawler.arun( urlhttps://example.com, configCrawlerRunConfig( magicTrue, # Simplifies a lot of interaction remove_overlay_elementsTrue, page_timeout60000 ) )Magic Mode 的行为模拟类人用户体验随机化 User-Agent 与 navigator 信息随机化交互与操作时序掩盖自动化信号尝试处理弹窗。在CrawlerRunConfig中magic参数默认值为Falseasync_configs.py 的参数说明将其定位为“自动处理 overlays/popups 的开关”。注意Magic Mode 不是真实用户会话的替代品——如果需要完全合法的身份化方案请使用 Managed Browsers。6. 对比Managed Browsers vs Magic Mode特性Managed BrowsersMagic Mode会话持久化user_data_dir 中完整保留 localStorage/cookies无持久数据每次全新开始真实身份带完整权限与偏好的真实用户 profile仅模拟类人行为无真实身份复杂站点最适合登录受限站点或重配置场景简单任务基本无登录或配置需求搭建成本需先外部创建 user_data_dir再交给 Crawl4AI单行配置magicTrue可靠性极高各次运行数据一致小任务表现良好稳定性可能稍弱7. 语言、时区与地理位置控制除了复用持久化 profileCrawl4AI 还支持定制浏览器的 locale、时区与地理位置用于控制网站对你“地域身份”的感知。7.1 设置 Locale 与时区通过CrawlerRunConfig设置from crawl4ai import AsyncWebCrawler, CrawlerRunConfig async with AsyncWebCrawler() as crawler: result await crawler.arun( urlhttps://example.com, configCrawlerRunConfig( # 设置浏览器 locale语言与区域格式 localefr-FR, # 法语法国 # 设置浏览器时区 timezone_idEurope/Paris, # 其他常规选项…… magicTrue, page_timeout60000 ) )工作机制locale影响语言偏好、日期格式、数字格式等timezone_id影响 JavaScript 的Date对象及一切时间相关功能两者在创建浏览器 context 时应用并在整个会话期间维持。在 async_configs.py 中CrawlerRunConfig声明了locale如en-US、timezone_id如America/New_York与geolocation三个字段并参与配置序列化to_dict因此也支持跨进程/远程场景传递。7.2 配置地理位置控制浏览器 Geolocation API 上报的 GPS 坐标from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, GeolocationConfig async with AsyncWebCrawler() as crawler: result await crawler.arun( urlhttps://maps.google.com, # 或任何依赖位置的站点 configCrawlerRunConfig( # 配置精确 GPS 坐标 geolocationGeolocationConfig( latitude48.8566, # 巴黎坐标 longitude2.3522, accuracy100 # 精度米可选 ), # 该站点会认为你在巴黎 page_timeout60000 ) )要点指定geolocation后浏览器会被自动授予位置访问权限使用 Geolocation API 的网站将收到你指定的精确坐标影响地图服务、门店定位、配送服务等与恰当的locale和timezone_id组合可构建完全自洽的位置画像。GeolocationConfig定义于 async_configs.pylatitude与longitude为必填浮点坐标accuracy表示精度米默认0.0。7.3 与 Managed Browsers 组合完整身份方案这些设置与托管浏览器配合构成完整的身份解决方案from crawl4ai import ( AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, GeolocationConfig ) browser_config BrowserConfig( use_managed_browserTrue, user_data_dir/path/to/my-profile, browser_typechromium ) crawl_config CrawlerRunConfig( # 位置相关设置 localees-MX, # 西班牙语墨西哥 timezone_idAmerica/Mexico_City, geolocationGeolocationConfig( latitude19.4326, # 墨西哥城 longitude-99.1332 ) ) async with AsyncWebCrawler(configbrowser_config) as crawler: result await crawler.arun(urlhttps://example.com, configcrawl_config)持久化 profile 精确地理信息 区域语言设置三者组合即构成对数字身份的完全控制。8. 小结创建user-data 目录的三条路径外部启动 Chrome/Chromium 并带--user-data-dir/some/pathBrowserProfiler.create_profile()或crwl profilesCLIprofiler.interactive_manager()交互界面。登录或按需配置站点然后关闭浏览器将该目录引用到BrowserConfig(user_data_dir..., use_managed_browserTrue)定制身份维度locale、timezone_id、geolocation列出与复用profileBrowserProfiler.list_profiles()、get_profile_path()管理profile删除delete_profile、压缩瘦身shrinkAGGRESSIVE档位在保留鉴权数据的前提下释放空间享受与你真实身份一致的持久化会话无需重复登录若只需要快速、临时的自动化Magic Mode即可胜任。推荐实践对于稳健的身份化爬虫与复杂站点的交互始终优先选择Managed BrowsersMagic Mode适合无需持久化数据的快速任务与原型验证。通过上述方式你可以维持一个真实的浏览环境让站点看到的你与普通用户无异——没有重复登录没有浪费时间。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考