fix(cloudflare): enable browser caching for images

Author: tangly1024

.gitignore

@@ -68,3 +68,6 @@ package-lock.json
 .perf/
 tsconfig.tsbuildinfo
 webpack-internal:/
+
+# Local Cloudflare Worker route configuration
+/cloudflare/notion-image-proxy/wrangler.toml

cloudflare/notion-image-proxy/README.md

@@ -2,6 +2,10 @@
 
 Cloudflare Worker proxy for NotionNext images.
 
+It keeps Notion attachment URLs in the browser and at Cloudflare's edge for one
+year. Fresh browser cache entries need no network request; explicit
+revalidation is answered with `304 Not Modified` when the validator matches.
+
 ## Deploy
 
 1. Copy `wrangler.toml.example` to `wrangler.toml`.
@@ -33,4 +37,23 @@ Expected headers after repeat requests:
 X-Notion-Image-Proxy: 1
 X-Notion-Image-Proxy-Cache: HIT
 CF-Cache-Status: HIT
+Cache-Control: public, max-age=31536000, s-maxage=31536000, immutable
+ETag: W/"..."
+```
+
+Verify conditional requests with the `Last-Modified` value returned above:
+
+```bash
+curl -I -H "If-Modified-Since: <Last-Modified value>" "https://cdn.example.com/image/..."
 ```
+
+The expected status is `304 Not Modified` with no image body.
+
+## Test
+
+```bash
+node --test worker.test.mjs
+```
+
+The test also checks that the copy-paste code in the VitePress tutorial stays
+identical to `worker.mjs`.

cloudflare/notion-image-proxy/worker.mjs

@@ -1,6 +1,5 @@
 const NOTION_ORIGIN = 'https://www.notion.so'
-const EDGE_TTL_SECONDS = 60 * 60 * 24 * 7
-const BROWSER_TTL_SECONDS = 60 * 60 * 24
+const IMMUTABLE_TTL_SECONDS = 60 * 60 * 24 * 365
 const USER_AGENT =
   'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36'
 
@@ -21,7 +20,12 @@ export default {
     const cached = await cache.match(cacheKey)
     if (cached) {
       const hitHeaders = new Headers(cached.headers)
+      setCacheHeaders(hitHeaders)
+      setValidatorHeaders(hitHeaders)
       hitHeaders.set('X-Notion-Image-Proxy-Cache', 'HIT')
+      if (isNotModified(request, hitHeaders)) {
+        return notModifiedResponse(hitHeaders)
+      }
       return new Response(request.method === 'HEAD' ? null : cached.body, {
         status: cached.status,
         statusText: cached.statusText,
@@ -35,20 +39,19 @@ export default {
       redirect: 'follow',
       cf: {
         cacheEverything: true,
-        cacheTtl: EDGE_TTL_SECONDS,
+        cacheTtl: IMMUTABLE_TTL_SECONDS,
         cacheKey: request.url
       },
       headers: {
         'User-Agent': USER_AGENT,
-        Accept: 'image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8'
+        Accept:
+          'image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8'
       }
     })
 
     const headers = new Headers(response.headers)
-    headers.set(
-      'Cache-Control',
-      `public, max-age=${BROWSER_TTL_SECONDS}, s-maxage=${EDGE_TTL_SECONDS}`
-    )
+    setCacheHeaders(headers)
+    setValidatorHeaders(headers)
     headers.set('X-Notion-Image-Proxy', '1')
     headers.set('X-Notion-Image-Proxy-Cache', 'MISS')
     headers.delete('set-cookie')
@@ -65,12 +68,64 @@ export default {
       await cache.put(cacheKey, proxied.clone())
     }
 
-    return request.method === 'HEAD'
-      ? new Response(null, proxied)
-      : proxied
+    if (isNotModified(request, headers)) {
+      return notModifiedResponse(headers)
+    }
+
+    return request.method === 'HEAD' ? new Response(null, proxied) : proxied
   }
 }
 
 function isAllowedPath(pathname) {
   return pathname.startsWith('/image/') || pathname.startsWith('/images/')
 }
+
+function setCacheHeaders(headers) {
+  headers.set(
+    'Cache-Control',
+    `public, max-age=${IMMUTABLE_TTL_SECONDS}, s-maxage=${IMMUTABLE_TTL_SECONDS}, immutable`
+  )
+}
+
+function setValidatorHeaders(headers) {
+  if (headers.has('etag')) return
+
+  const lastModified = Date.parse(headers.get('last-modified') || '')
+  const contentLength = headers.get('content-length') || 'unknown'
+  if (!Number.isNaN(lastModified)) {
+    headers.set('ETag', `W/"${lastModified.toString(16)}-${contentLength}"`)
+  }
+}
+
+function isNotModified(request, headers) {
+  const etag = headers.get('etag')
+  const ifNoneMatch = request.headers.get('if-none-match')
+  if (etag && ifNoneMatch) {
+    return ifNoneMatch
+      .split(',')
+      .map(value => value.trim())
+      .some(value => value === '*' || weakEtag(value) === weakEtag(etag))
+  }
+
+  const lastModified = Date.parse(headers.get('last-modified') || '')
+  const ifModifiedSince = Date.parse(
+    request.headers.get('if-modified-since') || ''
+  )
+  return (
+    !Number.isNaN(lastModified) &&
+    !Number.isNaN(ifModifiedSince) &&
+    lastModified <= ifModifiedSince
+  )
+}
+
+function weakEtag(value) {
+  return value.replace(/^W\//, '')
+}
+
+function notModifiedResponse(headers) {
+  const notModifiedHeaders = new Headers(headers)
+  notModifiedHeaders.delete('content-length')
+  notModifiedHeaders.delete('content-encoding')
+  notModifiedHeaders.delete('content-range')
+  return new Response(null, { status: 304, headers: notModifiedHeaders })
+}

cloudflare/notion-image-proxy/worker.test.mjs

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import test from 'node:test'
+
+import worker from './worker.mjs'
+
+test('serves immutable images and returns an empty 304 on revalidation', async () => {
+  const originalFetch = globalThis.fetch
+  const originalCaches = globalThis.caches
+  let stored
+
+  globalThis.fetch = async () =>
+    new Response('image-bytes', {
+      status: 200,
+      headers: {
+        'Content-Type': 'image/webp',
+        'Content-Length': '11',
+        'Last-Modified': 'Thu, 06 Aug 2026 11:27:52 GMT'
+      }
+    })
+  globalThis.caches = {
+    default: {
+      match: async () => stored?.clone(),
+      put: async (_key, response) => {
+        stored = response.clone()
+      }
+    }
+  }
+
+  try {
+    const url = 'https://cdn.example.com/image/example.png?id=page-id'
+    const first = await worker.fetch(new Request(url))
+    const etag = first.headers.get('etag')
+
+    assert.equal(first.status, 200)
+    assert.equal(
+      first.headers.get('cache-control'),
+      'public, max-age=31536000, s-maxage=31536000, immutable'
+    )
+    assert.match(etag, /^W\/"[a-f0-9]+-11"$/)
+
+    const byDate = await worker.fetch(
+      new Request(url, {
+        headers: {
+          'If-Modified-Since': 'Thu, 06 Aug 2026 11:27:52 GMT'
+        }
+      })
+    )
+    const byEtag = await worker.fetch(
+      new Request(url, { headers: { 'If-None-Match': etag } })
+    )
+
+    assert.equal(byDate.status, 304)
+    assert.equal(byEtag.status, 304)
+    assert.equal((await byDate.arrayBuffer()).byteLength, 0)
+    assert.equal((await byEtag.arrayBuffer()).byteLength, 0)
+  } finally {
+    globalThis.fetch = originalFetch
+    globalThis.caches = originalCaches
+  }
+})
+
+test('keeps the VitePress copy-paste example in sync with worker.mjs', async () => {
+  const workerSource = await readFile(
+    new URL('./worker.mjs', import.meta.url),
+    'utf8'
+  )
+  const tutorial = await readFile(
+    new URL(
+      '../../docs/user-guide/deploy/notion-image-proxy.md',
+      import.meta.url
+    ),
+    'utf8'
+  )
+  const example = tutorial.match(
+    /```js\r?\n(const NOTION_ORIGIN = [\s\S]*?)\r?\n```/
+  )
+
+  assert.ok(example, 'VitePress tutorial must include the Worker source')
+  assert.equal(normalize(example[1]), normalize(workerSource))
+})
+
+function normalize(value) {
+  return value.replace(/\r\n/g, '\n').trim()
+}

cloudflare/notion-image-proxy/wrangler.toml

@@ -19,6 +19,7 @@
 | [vercel-redeploy.md](./vercel-redeploy.md) | 重新部署 |
 | [netlify.md](./netlify.md) | Netlify（4.0.9+） |
 | [cloudflare-pages.md](./cloudflare-pages.md) | Cloudflare 静态 |
+| [notion-image-proxy.md](./notion-image-proxy.md) | Cloudflare Worker 图片反代、浏览器长期缓存与 304 验证 |
 | [edgeone-pages.md](./edgeone-pages.md) | **腾讯云 EdgeOne**（Node 版本、ENOSPC、Next SSG 预设） |
 | [build-tuning.md](./build-tuning.md) | **构建超时 / Notion 预热与限流**（环境变量） |
 | [vps.md](./vps.md) | VPS / Docker（Node 22+） |