From 070c87dc7ff4df7d0bf0100b0f904c21150e71dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=B3=96=E9=A5=BC?= <sugarpie.tang@gmail.com>
Date: Thu, 7 Aug 2025 11:00:40 +0800
Subject: [PATCH] docs: update

---
 README.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 57b2529..da26b0e 100644
--- a/README.md
+++ b/README.md
@@ -658,6 +658,8 @@ sharedCache: {
 }
 ```
 
+**⚠️ Performance Warning**: By default, SharedCache processes Vary headers which requires **two KV storage queries** per cache lookup. If you're using a slow KV storage (like remote Redis), this can significantly impact performance. Consider setting `ignoreVary: true` to disable Vary processing and use only one query per lookup.
+
 #### `cacheKeyRules`
 
 Customize how cache keys are generated to optimize cache hit rates and handle different caching scenarios:
@@ -1241,7 +1243,7 @@ interface CacheQueryOptions {
 **Unsupported Options (throw errors):**
 
 - **❌ `ignoreSearch`**: Query string handling not customizable
-- **❌ `ignoreVary`**: Vary header processing not bypassable
+- **❌ `ignoreVary`**: Vary header processing not bypassable (Note: This option is actually supported in SharedCache)
 
 ### 📊 Compliance Summary
 
@@ -1318,6 +1320,32 @@ When using SharedCache with meta-frameworks, you can develop with a consistent c
 - **stale-while-revalidate**: Serves cached content immediately while updating in background, providing zero-latency responses
 - **stale-if-error**: Serves cached content when origin servers fail, improving uptime and user experience
 
+### Q: How does SharedCache handle Vary headers and what are the performance implications?
+
+**A:** SharedCache processes Vary headers by default, which requires **two KV storage queries** per cache lookup:
+
+1. First query: Get Vary metadata from base cache key
+2. Second query: Get actual response from variant cache key
+
+**Performance Impact:**
+- **Local Redis**: Minimal impact (0.2-1ms additional latency)
+- **Remote Redis**: Significant impact (4-20ms additional latency)
+- **Database storage**: High impact (10-50ms additional latency)
+
+**Recommendation for slow storage:**
+```typescript
+// Disable Vary processing for better performance
+const fetch = createFetch(cache, {
+  sharedCache: {
+    ignoreVary: true, // Reduces to single query per lookup
+  },
+});
+```
+
+**Trade-offs:**
+- **With Vary**: RFC compliant, supports content negotiation, but slower
+- **Without Vary**: Faster performance, but may serve incorrect content for requests with different headers
+
 ```typescript
 // Best practice: Use both directives together
 const fetch = createFetch(cache, {