尧图网页设计 
Crawl4AI 缓存模式CacheMode完全指南从旧布尔开关迁移到 v0.5.0 的 enum 缓存体系【免费下载链接】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自 v0.5.0 起Crawl4AI 以更直观、行为更可预测的CacheMode枚举取代了旧版的多个布尔缓存开关bypass_cache、disable_cache、no_cache_read、no_cache_write。本文以官方缓存指南为主线结合仓库内 cache_context.py 等源码实现完整讲解五种缓存模式的含义、内部读写判定逻辑、迁移路径与典型实战用法帮助你精确控制爬虫何时读缓存、何时写缓存从而在抓取新鲜度与请求成本之间取得最佳平衡。一、为什么引入 CacheMode一次缓存的正交化重构1.1 旧系统的痛点在 v0.5.0 之前Crawl4AI 用一组互相独立的布尔参数来表达缓存意图bypass_cache完全跳过缓存相当于既不读也不写disable_cache禁用所有缓存no_cache_read不从缓存读取no_cache_write不向缓存写入。这些开关语义重叠且组合爆炸例如no_cache_readTrueno_cache_writeTrue实际等价于完全禁用使用者很难判断最终生效行为也极易写错。1.2 新系统的设计从 v0.5.0 起缓存行为被收敛为单一枚举CacheMode其定义位于仓库 crawl4ai/cache_context.pyfrom enum import Enum class CacheMode(Enum): ENABLED enabled # Normal caching behavior (read and write) DISABLED disabled # No caching at all READ_ONLY read_only # Only read from cache, dont write WRITE_ONLY write_only # Only write to cache, dont read BYPASS bypass # Bypass cache for this operation五种模式可以看作读 / 写两个维度的正交组合仅用一个参数即可精确表达任意缓存策略CacheMode读取缓存写入缓存适用场景CacheMode.ENABLED✅✅常规缓存命中即复用未命中则抓取并回填CacheMode.DISABLED❌❌本次操作完全不用缓存读、写均禁止CacheMode.READ_ONLY✅❌只想复用历史结果绝不更新缓存CacheMode.WRITE_ONLY❌✅强制重新抓取并把结果写回缓存预热/刷新CacheMode.BYPASS❌❌本次抓取跳过缓存层且不污染已有缓存注意从读写维度看BYPASS与DISABLED都表现为不读不写差异主要体现在代码语义上——BYPASS强调临时绕过一次而DISABLED强调彻底关闭。在设计迁移上两者各有明确的旧开关对应见第四节迁移表。二、源码视角缓存读写是如何被决策的指南只说清了模式是什么而真正解释模式如何生效的是CacheContext。在 crawl4ai/cache_context.py 中CacheContext把缓存决策与 URL 类型判断集中到一个类里让行为可预测、可维护。2.1 URL 可缓存性判定CacheContext构造时会根据 URL 前缀自动判别目标类型self.is_cacheable url.startswith((http://, https://, file://)) self.is_web_url url.startswith((http://, https://)) self.is_local_file url.startswith(file://) self.is_raw_html url.startswith(raw:)这里包含一条重要实现细节只有http(s)://与file://这类可从远端或本地源获取的目标才被视为可缓存而raw:调用方直接传入 HTML 源码类型不会被写入缓存——因为它根本没有可重复获取的源头缓存它没有意义。always_bypass参数为True时则无条件跳过缓存。2.2 读 / 写判定的核心逻辑真正决定是否读、是否写的是两个方法cache_context.pydef should_read(self) - bool: if self.always_bypass or not self.is_cacheable: return False return self.cache_mode in [CacheMode.ENABLED, CacheMode.READ_ONLY] def should_write(self) - bool: if self.always_bypass or not self.is_cacheable: return False return self.cache_mode in [CacheMode.ENABLED, CacheMode.WRITE_ONLY]可以看到判定由两层条件合成前提层always_bypassTrue或目标不可缓存如raw:→ 直接拒绝模式层只有ENABLED/READ_ONLY才允许读只有ENABLED/WRITE_ONLY才允许写。这正是第五节迁移映射表的源码级表达。2.3 在爬虫主流程中的落地在爬虫执行路径 async_webcrawler.py 中CacheContext被这样驱动# Default to ENABLED if no cache mode specified if config.cache_mode is None: config.cache_mode CacheMode.ENABLED cache_context CacheContext(url, config.cache_mode, False) # Try to get cached result if appropriate if cache_context.should_read(): cached_result await async_db_manager.aget_cached_url(url)命中缓存后会走短路返回分支直接产出结果只有未命中时才发起真实抓取并在成功抓取后按条件写库# Update cache if appropriate if cache_context.should_write() and not bool(cached_result): await async_db_manager.acache_url(crawl_result)这里还有一个值得注意的细节WRITE_ONLY模式下should_read()返回False因此必然触发真实抓取而写回的条件是should_write() and not cached_result保证只有本次确实产生了新结果时才会更新缓存避免覆盖。2.4 缓存结果的回放规则命中缓存时并不是无脑返回。在 async_webcrawler.py 中若用户本次请求了screenshot或pdf而缓存结果中恰好没有对应数据则该缓存会被判定为不可用cached_result None从而重新走一次真实抓取。这也是READ_ONLY模式下需要留意的一个行为复用缓存不意味着一定零抓取缺失的衍生资源仍会触发一次重新抓取。三、新旧代码对照从布尔参数到 CacheMode3.1 旧代码已废弃旧示例中的四个布尔开关在 v0.5 已被移除下面的代码仅作历史回顾不再可运行from crawl4ai import AsyncWebCrawler async def old_code(crawler: AsyncWebCrawler): # Legacy bypass_cache / disable_cache / no_cache_read / no_cache_write # were removed in v0.5. This example no longer applies: result await crawler.arun( urlhttps://www.nbcnews.com/business, # cache_mode is the only cache option now. ) print(len(result.markdown))3.2 新代码推荐新写法把缓存模式放进CrawlerRunConfig配合AsyncWebCrawler使用import asyncio from crawl4ai import AsyncWebCrawler, CacheMode from crawl4ai.async_configs import CrawlerRunConfig async def use_proxy(): # Use CacheMode in CrawlerRunConfig config CrawlerRunConfig(cache_modeCacheMode.BYPASS) async with AsyncWebCrawler(verboseTrue) as crawler: result await crawler.arun( urlhttps://www.nbcnews.com/business, configconfig # Pass the configuration object ) print(len(result.markdown)) async def main(): await use_proxy() if __name__ __main__: asyncio.run(main())四、迁移对照表四个旧开关 → 一个 CacheMode这是指南给出的官方迁移映射可直接作为你重构代码时的查表旧布尔参数替代写法bypass_cacheTruecache_modeCacheMode.BYPASSdisable_cacheTruecache_modeCacheMode.DISABLEDno_cache_readTruecache_modeCacheMode.READ_ONLYno_cache_writeTruecache_modeCacheMode.WRITE_ONLY结合第二节的读写判定逻辑这张表的正确性很容易验证旧bypass_cache语义 既不读也不写 →BYPASS旧disable_cache语义 完全不碰缓存 →DISABLED旧no_cache_read语义 只写不读 →WRITE_ONLY旧no_cache_write语义 只读不写 →READ_ONLY。从实现层面看仓库还保留了一个内部转换函数_legacy_to_cache_mode()cache_context.py它把旧布尔参数按disable_cache bypass_cache no_cache_read/no_cache_write的优先级换算成对应CacheMode用于平滑过渡同时也印证了上述映射并非随意约定而是与旧语义逐一对齐的。五、五种模式的实战选择建议5.1CacheMode.ENABLED常规读写缓存适合内容相对稳定、希望先读缓存、未命中再抓并回填的常规任务。这是缓存收益最大的模式同一 URL 重复抓取时直接命中显著降低带宽与浏览器资源开销。5.2CacheMode.BYPASS每次强制新鲜抓取适合价格敏感型页面、需要实时数据或用于验证反爬策略的场景。注意它的语义是跳过缓存而不是删掉缓存——已有的历史缓存不会被清除只是本次不读不写。5.3CacheMode.READ_ONLY只复用历史数据适合对同一批 URL 做多轮后处理例如先爬一遍存结果随后用不同抽取策略反复分析此时只读缓存即可同时保证绝不覆盖已沉淀的数据。5.4CacheMode.WRITE_ONLY强制刷新并预热缓存适合定时任务里强制更新的环节无视旧缓存重新抓取并把新结果写回让后续ENABLED/READ_ONLY的调用都能命中最新数据。可配合先预热再读取的两阶段流程使用。5.5CacheMode.DISABLED彻底关闭缓存适合调试、排障等希望完全隔离缓存干扰的场景。它等价于对当前操作同时关闭读与写。六、缓存行为的可观测性cache_status 字段指南未展开但源码补充了一个极其实用的诊断字段。每一次抓取的结果CrawlResult上都会带上cache_status标记models.py取值包括hit直接命中缓存并返回hit_validated命中且通过了新鲜度校验hit_fallback校验失败但回退使用了缓存miss缓存未命中走了真实抓取。你可以借助该字段统计命中率、验证缓存模式是否按预期生效import asyncio from crawl4ai import AsyncWebCrawler, CacheMode from crawl4ai.async_configs import CrawlerRunConfig async def inspect_cache_status(): config CrawlerRunConfig(cache_modeCacheMode.ENABLED) async with AsyncWebCrawler() as crawler: r1 await crawler.arun(urlhttps://example.com, configconfig) print(第一次:, r1.cache_status) # miss首抓 r2 await crawler.arun(urlhttps://example.com, configconfig) print(第二次:, r2.cache_status) # hit命中 asyncio.run(inspect_cache_status())七、相关配置与默认值说明cache_mode是CrawlerRunConfig的构造参数定义于 async_configs.py。同一配置类中还保留了bypass_cache、disable_cache、no_cache_read、no_cache_write四个参数位async_configs.py但其文档明确标注为Legacy parameter并给出指向新写法的替代建议新代码应统一使用cache_mode。如果你从旧代码迁移请对照第四节表格做一次性替换避免新旧参数混用带来的语义歧义。与之相邻的还有一组新鲜度增强参数check_cache_freshness默认False与cache_validation_timeout默认10.0秒。当check_cache_freshnessTrue且模式允许读缓存时Crawl4AI 会通过 ETag / Last-Modified / head 指纹等条件请求校验缓存是否过期见 async_webcrawler.py将命中但可能过期的缓存智能标记为 stale 并触发重新抓取——这正是hit_validated/hit_fallback两种状态产生的来源。追求既省流量又不吃陈数据的读者可以进一步阅读仓库中 cache_validator.py 了解校验实现。八、小结Crawl4AI 的缓存模式演进本质上是一次从多个互相纠缠的布尔开关到单一枚举 集中决策类的重构CacheMode负责表达意图CacheContextcrawl4ai/cache_context.py负责把意图翻译成should_read/should_write的确定性判定而爬虫主流程async_webcrawler.py据此决定是读缓存短路返回还是真实抓取后回写。无论是迁移旧代码、为批量抓取设计预热/读取两阶段流水线还是排查为什么没走缓存理解这五个模式与它们的读写矩阵都是精确控制 Crawl4AI 缓存行为的关键。【免费下载链接】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），仅供参考 Crawl4AI 缓存模式（CacheMode）完全指南：从旧布尔开关迁移到 v0.5.0+ 的 enum 缓存体系
Crawl4AI 缓存模式CacheMode完全指南从旧布尔开关迁移到 v0.5.0 的 enum 缓存体系【免费下载链接】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自 v0.5.0 起Crawl4AI 以更直观、行为更可预测的CacheMode枚举取代了旧版的多个布尔缓存开关bypass_cache、disable_cache、no_cache_read、no_cache_write。本文以官方缓存指南为主线结合仓库内 cache_context.py 等源码实现完整讲解五种缓存模式的含义、内部读写判定逻辑、迁移路径与典型实战用法帮助你精确控制爬虫何时读缓存、何时写缓存从而在抓取新鲜度与请求成本之间取得最佳平衡。一、为什么引入 CacheMode一次缓存的正交化重构1.1 旧系统的痛点在 v0.5.0 之前Crawl4AI 用一组互相独立的布尔参数来表达缓存意图bypass_cache完全跳过缓存相当于既不读也不写disable_cache禁用所有缓存no_cache_read不从缓存读取no_cache_write不向缓存写入。这些开关语义重叠且组合爆炸例如no_cache_readTrueno_cache_writeTrue实际等价于完全禁用使用者很难判断最终生效行为也极易写错。1.2 新系统的设计从 v0.5.0 起缓存行为被收敛为单一枚举CacheMode其定义位于仓库 crawl4ai/cache_context.pyfrom enum import Enum class CacheMode(Enum): ENABLED enabled # Normal caching behavior (read and write) DISABLED disabled # No caching at all READ_ONLY read_only # Only read from cache, dont write WRITE_ONLY write_only # Only write to cache, dont read BYPASS bypass # Bypass cache for this operation五种模式可以看作读 / 写两个维度的正交组合仅用一个参数即可精确表达任意缓存策略CacheMode读取缓存写入缓存适用场景CacheMode.ENABLED✅✅常规缓存命中即复用未命中则抓取并回填CacheMode.DISABLED❌❌本次操作完全不用缓存读、写均禁止CacheMode.READ_ONLY✅❌只想复用历史结果绝不更新缓存CacheMode.WRITE_ONLY❌✅强制重新抓取并把结果写回缓存预热/刷新CacheMode.BYPASS❌❌本次抓取跳过缓存层且不污染已有缓存注意从读写维度看BYPASS与DISABLED都表现为不读不写差异主要体现在代码语义上——BYPASS强调临时绕过一次而DISABLED强调彻底关闭。在设计迁移上两者各有明确的旧开关对应见第四节迁移表。二、源码视角缓存读写是如何被决策的指南只说清了模式是什么而真正解释模式如何生效的是CacheContext。在 crawl4ai/cache_context.py 中CacheContext把缓存决策与 URL 类型判断集中到一个类里让行为可预测、可维护。2.1 URL 可缓存性判定CacheContext构造时会根据 URL 前缀自动判别目标类型self.is_cacheable url.startswith((http://, https://, file://)) self.is_web_url url.startswith((http://, https://)) self.is_local_file url.startswith(file://) self.is_raw_html url.startswith(raw:)这里包含一条重要实现细节只有http(s)://与file://这类可从远端或本地源获取的目标才被视为可缓存而raw:调用方直接传入 HTML 源码类型不会被写入缓存——因为它根本没有可重复获取的源头缓存它没有意义。always_bypass参数为True时则无条件跳过缓存。2.2 读 / 写判定的核心逻辑真正决定是否读、是否写的是两个方法cache_context.pydef should_read(self) - bool: if self.always_bypass or not self.is_cacheable: return False return self.cache_mode in [CacheMode.ENABLED, CacheMode.READ_ONLY] def should_write(self) - bool: if self.always_bypass or not self.is_cacheable: return False return self.cache_mode in [CacheMode.ENABLED, CacheMode.WRITE_ONLY]可以看到判定由两层条件合成前提层always_bypassTrue或目标不可缓存如raw:→ 直接拒绝模式层只有ENABLED/READ_ONLY才允许读只有ENABLED/WRITE_ONLY才允许写。这正是第五节迁移映射表的源码级表达。2.3 在爬虫主流程中的落地在爬虫执行路径 async_webcrawler.py 中CacheContext被这样驱动# Default to ENABLED if no cache mode specified if config.cache_mode is None: config.cache_mode CacheMode.ENABLED cache_context CacheContext(url, config.cache_mode, False) # Try to get cached result if appropriate if cache_context.should_read(): cached_result await async_db_manager.aget_cached_url(url)命中缓存后会走短路返回分支直接产出结果只有未命中时才发起真实抓取并在成功抓取后按条件写库# Update cache if appropriate if cache_context.should_write() and not bool(cached_result): await async_db_manager.acache_url(crawl_result)这里还有一个值得注意的细节WRITE_ONLY模式下should_read()返回False因此必然触发真实抓取而写回的条件是should_write() and not cached_result保证只有本次确实产生了新结果时才会更新缓存避免覆盖。2.4 缓存结果的回放规则命中缓存时并不是无脑返回。在 async_webcrawler.py 中若用户本次请求了screenshot或pdf而缓存结果中恰好没有对应数据则该缓存会被判定为不可用cached_result None从而重新走一次真实抓取。这也是READ_ONLY模式下需要留意的一个行为复用缓存不意味着一定零抓取缺失的衍生资源仍会触发一次重新抓取。三、新旧代码对照从布尔参数到 CacheMode3.1 旧代码已废弃旧示例中的四个布尔开关在 v0.5 已被移除下面的代码仅作历史回顾不再可运行from crawl4ai import AsyncWebCrawler async def old_code(crawler: AsyncWebCrawler): # Legacy bypass_cache / disable_cache / no_cache_read / no_cache_write # were removed in v0.5. This example no longer applies: result await crawler.arun( urlhttps://www.nbcnews.com/business, # cache_mode is the only cache option now. ) print(len(result.markdown))3.2 新代码推荐新写法把缓存模式放进CrawlerRunConfig配合AsyncWebCrawler使用import asyncio from crawl4ai import AsyncWebCrawler, CacheMode from crawl4ai.async_configs import CrawlerRunConfig async def use_proxy(): # Use CacheMode in CrawlerRunConfig config CrawlerRunConfig(cache_modeCacheMode.BYPASS) async with AsyncWebCrawler(verboseTrue) as crawler: result await crawler.arun( urlhttps://www.nbcnews.com/business, configconfig # Pass the configuration object ) print(len(result.markdown)) async def main(): await use_proxy() if __name__ __main__: asyncio.run(main())四、迁移对照表四个旧开关 → 一个 CacheMode这是指南给出的官方迁移映射可直接作为你重构代码时的查表旧布尔参数替代写法bypass_cacheTruecache_modeCacheMode.BYPASSdisable_cacheTruecache_modeCacheMode.DISABLEDno_cache_readTruecache_modeCacheMode.READ_ONLYno_cache_writeTruecache_modeCacheMode.WRITE_ONLY结合第二节的读写判定逻辑这张表的正确性很容易验证旧bypass_cache语义 既不读也不写 →BYPASS旧disable_cache语义 完全不碰缓存 →DISABLED旧no_cache_read语义 只写不读 →WRITE_ONLY旧no_cache_write语义 只读不写 →READ_ONLY。从实现层面看仓库还保留了一个内部转换函数_legacy_to_cache_mode()cache_context.py它把旧布尔参数按disable_cache bypass_cache no_cache_read/no_cache_write的优先级换算成对应CacheMode用于平滑过渡同时也印证了上述映射并非随意约定而是与旧语义逐一对齐的。五、五种模式的实战选择建议5.1CacheMode.ENABLED常规读写缓存适合内容相对稳定、希望先读缓存、未命中再抓并回填的常规任务。这是缓存收益最大的模式同一 URL 重复抓取时直接命中显著降低带宽与浏览器资源开销。5.2CacheMode.BYPASS每次强制新鲜抓取适合价格敏感型页面、需要实时数据或用于验证反爬策略的场景。注意它的语义是跳过缓存而不是删掉缓存——已有的历史缓存不会被清除只是本次不读不写。5.3CacheMode.READ_ONLY只复用历史数据适合对同一批 URL 做多轮后处理例如先爬一遍存结果随后用不同抽取策略反复分析此时只读缓存即可同时保证绝不覆盖已沉淀的数据。5.4CacheMode.WRITE_ONLY强制刷新并预热缓存适合定时任务里强制更新的环节无视旧缓存重新抓取并把新结果写回让后续ENABLED/READ_ONLY的调用都能命中最新数据。可配合先预热再读取的两阶段流程使用。5.5CacheMode.DISABLED彻底关闭缓存适合调试、排障等希望完全隔离缓存干扰的场景。它等价于对当前操作同时关闭读与写。六、缓存行为的可观测性cache_status 字段指南未展开但源码补充了一个极其实用的诊断字段。每一次抓取的结果CrawlResult上都会带上cache_status标记models.py取值包括hit直接命中缓存并返回hit_validated命中且通过了新鲜度校验hit_fallback校验失败但回退使用了缓存miss缓存未命中走了真实抓取。你可以借助该字段统计命中率、验证缓存模式是否按预期生效import asyncio from crawl4ai import AsyncWebCrawler, CacheMode from crawl4ai.async_configs import CrawlerRunConfig async def inspect_cache_status(): config CrawlerRunConfig(cache_modeCacheMode.ENABLED) async with AsyncWebCrawler() as crawler: r1 await crawler.arun(urlhttps://example.com, configconfig) print(第一次:, r1.cache_status) # miss首抓 r2 await crawler.arun(urlhttps://example.com, configconfig) print(第二次:, r2.cache_status) # hit命中 asyncio.run(inspect_cache_status())七、相关配置与默认值说明cache_mode是CrawlerRunConfig的构造参数定义于 async_configs.py。同一配置类中还保留了bypass_cache、disable_cache、no_cache_read、no_cache_write四个参数位async_configs.py但其文档明确标注为Legacy parameter并给出指向新写法的替代建议新代码应统一使用cache_mode。如果你从旧代码迁移请对照第四节表格做一次性替换避免新旧参数混用带来的语义歧义。与之相邻的还有一组新鲜度增强参数check_cache_freshness默认False与cache_validation_timeout默认10.0秒。当check_cache_freshnessTrue且模式允许读缓存时Crawl4AI 会通过 ETag / Last-Modified / head 指纹等条件请求校验缓存是否过期见 async_webcrawler.py将命中但可能过期的缓存智能标记为 stale 并触发重新抓取——这正是hit_validated/hit_fallback两种状态产生的来源。追求既省流量又不吃陈数据的读者可以进一步阅读仓库中 cache_validator.py 了解校验实现。八、小结Crawl4AI 的缓存模式演进本质上是一次从多个互相纠缠的布尔开关到单一枚举 集中决策类的重构CacheMode负责表达意图CacheContextcrawl4ai/cache_context.py负责把意图翻译成should_read/should_write的确定性判定而爬虫主流程async_webcrawler.py据此决定是读缓存短路返回还是真实抓取后回写。无论是迁移旧代码、为批量抓取设计预热/读取两阶段流水线还是排查为什么没走缓存理解这五个模式与它们的读写矩阵都是精确控制 Crawl4AI 缓存行为的关键。【免费下载链接】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），仅供参考