Miniflare 中的 Cache 模拟在本地完整复刻 Workers 缓存 API 的读、写、持久化与清除【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本文介绍 Cloudflare 官方文档中 Miniflare 的 Cache缓存模拟功能如何在本地测试环境中启用默认的caches.default与命名缓存、通过cachePersist将缓存落盘、借助getCaches在 Worker 之外直接读写缓存以及使用purgeCache清空缓存和cache: false整体禁用缓存。读完后你可以用 Miniflare 搭建一个与 Workers 运行时行为一致的缓存测试环境对“缓存命中/回源”逻辑做可重复、可断言的集成测试。Miniflare 缓存模拟的定位Workers 运行时提供全局的Cache APIcaches.default用于对 Cloudflare 边缘缓存做细粒度的读写控制详见 Cache Reference。但生产边缘缓存无法在本地复现Miniflare 作为低层模拟器在本地 workerd 沙箱中模拟出一套行为对齐的缓存对象让测试可以命中/写入缓存并断言结果在测试进程Node.js 侧直接操作缓存而不必全部走dispatchFetch控制缓存是否持久化到文件系统。需要注意一条与线上一致的边界Miniflare 文档明确提示通过fetch使用缓存即 fetch 的缓存模式与 tiered caching 路径在模拟中不受支持可参考 How the cache works 中 Cache API 一节了解线上语义。默认缓存caches.default对默认缓存的访问默认就是开启的无需额外配置项在 Worker 脚本里直接使用全局caches.default即可addEventListener(fetch, (e) { e.respondWith(caches.default.match(http://miniflare.dev)); });这与 Workers 运行时的形态一致caches.default受浏览器 Cache API 启发但 Workers 运行时暴露的是单个全局缓存对象Cache Reference。在 Miniflare 中match()未命中时同样返回undefined而不会向回源发出请求行为语义可放心依赖。命名缓存caches.open除了默认缓存可以通过open打开带命名空间的缓存实例await caches.open(cache_name);有一个硬性约束缓存名不能叫default尝试这样做会直接抛出错误——这是为了保留caches.default这一全局对象的命名空间也是线上与本地行为一致的地方。持久化cachePersist默认情况下Miniflare 的缓存数据只保存在内存中在同一个 Miniflare 实例内多次dispatchFetch重载时缓存可以跨请求保留persist between reloads但不会跨不同的Miniflare实例保留——重新new Miniflare(...)后缓存从零开始。如果测试需要在进程重启之间保留缓存数据可以通过cachePersist选项把缓存持久化到文件系统const mf new Miniflare({ cachePersist: true, // Defaults to ./.mf/cache cachePersist: ./data, // Custom path });参数说明结合 Miniflare 完整 API Reference 中 storage 段的定义选项取值说明cachePersist: true布尔启用持久化默认落盘目录为./.mf/cachecachePersist: ./data字符串启用持久化并指定自定义目录不设置—默认行为仅内存缓存Miniflare 对 KVkvPersist、R2r2Persist、Durable ObjectsdurableObjectsPersist也都有同构的持久化选项cachePersist只是其中针对缓存的那一个配置风格完全一致便于统一管理本地测试数据目录。在 Worker 之外操作缓存getCaches测试中一个常见需求是不经由 HTTP 请求直接往缓存里塞数据或读取缓存结果。Miniflare 提供getCaches方法返回沙箱内那个全局CacheStorage对象即 Worker 里caches的同一个实例因此外部写入的数据 Worker 立刻可见反之亦然。完整示例来自原文档import { Miniflare, Response } from miniflare; const mf new Miniflare({ modules: true, script: export default { async fetch(request) { const url new URL(request.url); const cache caches.default; if(url.pathname /put) { await cache.put(https://miniflare.dev/, new Response(1, { headers: { Cache-Control: max-age3600 }, })); } return cache.match(https://miniflare.dev/); } } , }); let res await mf.dispatchFetch(http://localhost:8787/put); console.log(await res.text()); // 1 const caches await mf.getCaches(); // Gets the global caches object const cachedRes await caches.default.match(https://miniflare.dev/); console.log(await cachedRes.text()); // 1 await caches.default.put( https://miniflare.dev, new Response(2, { headers: { Cache-Control: max-age3600 }, }), ); res await mf.dispatchFetch(http://localhost:8787); console.log(await res.text()); // 2这个例子完整展示了“缓存共享”的三条证据链通过mf.dispatchFetch(http://localhost:8787/put)让 Worker 执行cache.put写入1带Cache-Control: max-age3600使其可缓存随后在Node 侧用await mf.getCaches()拿到同一个缓存caches.default.match(https://miniflare.dev/)直接读回1——证明外部拿到的是沙箱内的同一份全局缓存再在 Node 侧caches.default.put(...)写入2回到 HTTP 侧dispatchFetch后 Worker 的cache.match返回2——证明外部写入对 Worker 立即可见。两点实现细节值得注意示例 Worker 使用modules: trueESM 模式通过script内联脚本getCaches返回的CacheStorage实例既可以用caches.default访问默认缓存也可以caches.open(name)访问命名缓存API Reference 中的调用形态即为const defaultCache caches.default; const namedCache await caches.open(name);。缓存写入遵循与线上 Cache API 相同的头部规则put()会解析响应上的Cache-Control、Cache-Tag、ETag、Expires、Last-Modified等头部带Set-Cookie的响应不会被缓存见 Cache Reference 的 Headers 一节。示例中特意带上Cache-Control: max-age3600正是为了让put成功生效。清除缓存purgeCache开发过程中经常需要“清掉缓存再继续测试”但又不想销毁整个 Miniflare 实例。Miniflare实例提供purgeCache方法可编程地清空整个缓存并返回被清除的条目数可用于断言const mf new Miniflare({ /* options */ }); // Purge the default cache and get the number of entries purged const count await mf.purgeCache(); console.log(Purged ${count} entries); // Purge a specific named cache await mf.purgeCache(my-named-cache);await mf.purgeCache()无参时清除默认缓存返回被清除条目的数量await mf.purgeCache(my-named-cache)传入缓存名时只清除对应命名缓存。在测试断言场景里返回的条目数很有用——可以在put之后purgeCache断言计数与写入次数一致从而验证缓存确实按预期积累了多少条目。禁用缓存cache: false如果某个测试场景例如纯回源逻辑的测试不需要任何缓存参与可以通过cache选项整体关闭const mf new Miniflare({ cache: false, });关键语义禁用后缓存对象在沙箱中依然存在caches.default、caches.open仍然可用不会抛错只是不再缓存任何内容——put不会生效、match永远未命中。这个“可用但空转”的设计对开发期非常友好同一份 Worker 代码在开/关缓存两种配置下都能运行测试可以根据场景按需切换而不必为缓存写防御性分支。从 Miniflare 完整配置参考 可以看到缓存相关共有三个选项配合使用选项默认作用cachetrue是否启用默认/命名缓存设为false后缓存可用但不缓存任何内容cachePersist不设置缓存数据落盘路径true表示默认./.mf/cache字符串表示自定义路径cacheWarnUsage—在workers.dev子域场景下对缓存使用发出警告使用建议小结默认场景不配置任何缓存选项即可caches.default开箱即用命名缓存用caches.open勿命名default需要跨进程保留测试数据加cachePersist: true或自定义目录需要测试预置/校验缓存状态用await mf.getCaches()在 Node 侧直接put/match/delete与 Worker 共享同一实例需要每轮测试从干净状态开始调用await mf.purgeCache()或指定缓存名清空并拿到清除条数不必重启实例回源逻辑测试cache: false让缓存“存在但空转”代码零改动。更广泛的 Miniflare 测试用法dispatchFetch、getBindings、模块图自动遍历、自定义构建管线可继续参考 Writing tests缓存线上语义的细节可参考 How the cache works 与 Cache Reference。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Miniflare 中的 Cache 模拟：在本地完整复刻 Workers 缓存 API 的读、写、持久化与清除
Miniflare 中的 Cache 模拟在本地完整复刻 Workers 缓存 API 的读、写、持久化与清除【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本文介绍 Cloudflare 官方文档中 Miniflare 的 Cache缓存模拟功能如何在本地测试环境中启用默认的caches.default与命名缓存、通过cachePersist将缓存落盘、借助getCaches在 Worker 之外直接读写缓存以及使用purgeCache清空缓存和cache: false整体禁用缓存。读完后你可以用 Miniflare 搭建一个与 Workers 运行时行为一致的缓存测试环境对“缓存命中/回源”逻辑做可重复、可断言的集成测试。Miniflare 缓存模拟的定位Workers 运行时提供全局的Cache APIcaches.default用于对 Cloudflare 边缘缓存做细粒度的读写控制详见 Cache Reference。但生产边缘缓存无法在本地复现Miniflare 作为低层模拟器在本地 workerd 沙箱中模拟出一套行为对齐的缓存对象让测试可以命中/写入缓存并断言结果在测试进程Node.js 侧直接操作缓存而不必全部走dispatchFetch控制缓存是否持久化到文件系统。需要注意一条与线上一致的边界Miniflare 文档明确提示通过fetch使用缓存即 fetch 的缓存模式与 tiered caching 路径在模拟中不受支持可参考 How the cache works 中 Cache API 一节了解线上语义。默认缓存caches.default对默认缓存的访问默认就是开启的无需额外配置项在 Worker 脚本里直接使用全局caches.default即可addEventListener(fetch, (e) { e.respondWith(caches.default.match(http://miniflare.dev)); });这与 Workers 运行时的形态一致caches.default受浏览器 Cache API 启发但 Workers 运行时暴露的是单个全局缓存对象Cache Reference。在 Miniflare 中match()未命中时同样返回undefined而不会向回源发出请求行为语义可放心依赖。命名缓存caches.open除了默认缓存可以通过open打开带命名空间的缓存实例await caches.open(cache_name);有一个硬性约束缓存名不能叫default尝试这样做会直接抛出错误——这是为了保留caches.default这一全局对象的命名空间也是线上与本地行为一致的地方。持久化cachePersist默认情况下Miniflare 的缓存数据只保存在内存中在同一个 Miniflare 实例内多次dispatchFetch重载时缓存可以跨请求保留persist between reloads但不会跨不同的Miniflare实例保留——重新new Miniflare(...)后缓存从零开始。如果测试需要在进程重启之间保留缓存数据可以通过cachePersist选项把缓存持久化到文件系统const mf new Miniflare({ cachePersist: true, // Defaults to ./.mf/cache cachePersist: ./data, // Custom path });参数说明结合 Miniflare 完整 API Reference 中 storage 段的定义选项取值说明cachePersist: true布尔启用持久化默认落盘目录为./.mf/cachecachePersist: ./data字符串启用持久化并指定自定义目录不设置—默认行为仅内存缓存Miniflare 对 KVkvPersist、R2r2Persist、Durable ObjectsdurableObjectsPersist也都有同构的持久化选项cachePersist只是其中针对缓存的那一个配置风格完全一致便于统一管理本地测试数据目录。在 Worker 之外操作缓存getCaches测试中一个常见需求是不经由 HTTP 请求直接往缓存里塞数据或读取缓存结果。Miniflare 提供getCaches方法返回沙箱内那个全局CacheStorage对象即 Worker 里caches的同一个实例因此外部写入的数据 Worker 立刻可见反之亦然。完整示例来自原文档import { Miniflare, Response } from miniflare; const mf new Miniflare({ modules: true, script: export default { async fetch(request) { const url new URL(request.url); const cache caches.default; if(url.pathname /put) { await cache.put(https://miniflare.dev/, new Response(1, { headers: { Cache-Control: max-age3600 }, })); } return cache.match(https://miniflare.dev/); } } , }); let res await mf.dispatchFetch(http://localhost:8787/put); console.log(await res.text()); // 1 const caches await mf.getCaches(); // Gets the global caches object const cachedRes await caches.default.match(https://miniflare.dev/); console.log(await cachedRes.text()); // 1 await caches.default.put( https://miniflare.dev, new Response(2, { headers: { Cache-Control: max-age3600 }, }), ); res await mf.dispatchFetch(http://localhost:8787); console.log(await res.text()); // 2这个例子完整展示了“缓存共享”的三条证据链通过mf.dispatchFetch(http://localhost:8787/put)让 Worker 执行cache.put写入1带Cache-Control: max-age3600使其可缓存随后在Node 侧用await mf.getCaches()拿到同一个缓存caches.default.match(https://miniflare.dev/)直接读回1——证明外部拿到的是沙箱内的同一份全局缓存再在 Node 侧caches.default.put(...)写入2回到 HTTP 侧dispatchFetch后 Worker 的cache.match返回2——证明外部写入对 Worker 立即可见。两点实现细节值得注意示例 Worker 使用modules: trueESM 模式通过script内联脚本getCaches返回的CacheStorage实例既可以用caches.default访问默认缓存也可以caches.open(name)访问命名缓存API Reference 中的调用形态即为const defaultCache caches.default; const namedCache await caches.open(name);。缓存写入遵循与线上 Cache API 相同的头部规则put()会解析响应上的Cache-Control、Cache-Tag、ETag、Expires、Last-Modified等头部带Set-Cookie的响应不会被缓存见 Cache Reference 的 Headers 一节。示例中特意带上Cache-Control: max-age3600正是为了让put成功生效。清除缓存purgeCache开发过程中经常需要“清掉缓存再继续测试”但又不想销毁整个 Miniflare 实例。Miniflare实例提供purgeCache方法可编程地清空整个缓存并返回被清除的条目数可用于断言const mf new Miniflare({ /* options */ }); // Purge the default cache and get the number of entries purged const count await mf.purgeCache(); console.log(Purged ${count} entries); // Purge a specific named cache await mf.purgeCache(my-named-cache);await mf.purgeCache()无参时清除默认缓存返回被清除条目的数量await mf.purgeCache(my-named-cache)传入缓存名时只清除对应命名缓存。在测试断言场景里返回的条目数很有用——可以在put之后purgeCache断言计数与写入次数一致从而验证缓存确实按预期积累了多少条目。禁用缓存cache: false如果某个测试场景例如纯回源逻辑的测试不需要任何缓存参与可以通过cache选项整体关闭const mf new Miniflare({ cache: false, });关键语义禁用后缓存对象在沙箱中依然存在caches.default、caches.open仍然可用不会抛错只是不再缓存任何内容——put不会生效、match永远未命中。这个“可用但空转”的设计对开发期非常友好同一份 Worker 代码在开/关缓存两种配置下都能运行测试可以根据场景按需切换而不必为缓存写防御性分支。从 Miniflare 完整配置参考 可以看到缓存相关共有三个选项配合使用选项默认作用cachetrue是否启用默认/命名缓存设为false后缓存可用但不缓存任何内容cachePersist不设置缓存数据落盘路径true表示默认./.mf/cache字符串表示自定义路径cacheWarnUsage—在workers.dev子域场景下对缓存使用发出警告使用建议小结默认场景不配置任何缓存选项即可caches.default开箱即用命名缓存用caches.open勿命名default需要跨进程保留测试数据加cachePersist: true或自定义目录需要测试预置/校验缓存状态用await mf.getCaches()在 Node 侧直接put/match/delete与 Worker 共享同一实例需要每轮测试从干净状态开始调用await mf.purgeCache()或指定缓存名清空并拿到清除条数不必重启实例回源逻辑测试cache: false让缓存“存在但空转”代码零改动。更广泛的 Miniflare 测试用法dispatchFetch、getBindings、模块图自动遍历、自定义构建管线可继续参考 Writing tests缓存线上语义的细节可参考 How the cache works 与 Cache Reference。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考