Next.js 15 强弱 ETag 与条件请求治理实践

正文ETag（实体标签）是 HTTP 条件请求的核心。强 ETag 适用于字节级一致性判断，弱 ETag 适用于语义一致但字节可能不同的场景（例如：相同数据经不同格式化）。本文给出强/弱 ETag 的生成与 `If-None-Match`、`If-Modified-Since` 的协同治理实践。

一、强/弱 ETag 生成方法// app/api/etag/route.ts

export const runtime = 'edge'

async function strongETag(input: ArrayBuffer) {

const digest = await crypto.subtle.digest('SHA-256', input)

const bytes = new Uint8Array(digest)

let b64 = ''

for (let i = 0; i < bytes.length; i++) b64 += String.fromCharCode(bytes[i])

return '"sha256-' + btoa(b64) + '"'

}

function weakETag(size: number, mtimeMs: number) {

return `W/"${size}-${mtimeMs}"`

}

二、条件请求与 304 响应治理优先使用 ETag 校验，其次使用 `Last-Modified` 与 `If-Modified-Since`。始终在 304 响应中回显当前的标准化响应头（ETag/Last-Modified/Cache-Control），确保中间缓存层的一致性。export async function GET(req: Request) {

// 示例资源：真实场景可来自存储/渲染结果

const body = new TextEncoder().encode('Hello ETag v2')

const lastModified = new Date('2025-11-01T00:00:00Z')

const strong = await strongETag(body.buffer)

const weak = weakETag(body.byteLength, lastModified.getTime())

const inm = req.headers.get('if-none-match') || ''

const ims = req.headers.get('if-modified-since')

// 优先 ETag 校验；兼容强/弱标签

if (inm && (inm.includes(strong) || inm.includes(weak))) {

return new Response(null, {

status: 304,

headers: {

ETag: strong,

'Last-Modified': lastModified.toUTCString(),

'Cache-Control': 'public, max-age=60, s-maxage=300, must-revalidate'

}

})

}

// 次选 Last-Modified 校验

if (ims) {

const imsDate = new Date(ims)

if (!Number.isNaN(imsDate.getTime()) && imsDate.getTime() >= lastModified.getTime()) {

return new Response(null, {

status: 304,

headers: {

ETag: strong,

'Last-Modified': lastModified.toUTCString(),

'Cache-Control': 'public, max-age=60, s-maxage=300, must-revalidate'

}

})

}

}

// 命中失败：返回资源与标准缓存头

return new Response(body, {

headers: {

'Content-Type': 'text/plain; charset=utf-8',

ETag: strong,

'Last-Modified': lastModified.toUTCString(),

'Cache-Control': 'public, max-age=60, s-maxage=300, stale-while-revalidate=600',

'Vary': 'Accept-Encoding'

}

})

}

三、选型建议与注意事项强 ETag：适合静态资源、经过完整哈希的产物（如构建输出），确保字节级一致。弱 ETag：适合语义一致但字节可能不同的场景（JSON 序列化差异、空白字符变化），提高命中率但不用于 Range 请求合并。回显策略：在 304 响应中始终回显当前 ETag 与 Last-Modified，避免中间层状态偏差。`Vary` 管理：仅在必要的协商维度（如 `Accept-Encoding`、`Accept`、UA-CH）设置 `Vary`，防止缓存分片过度导致命中率下降。安全与一致性：为动态生成内容设置合理的 `max-age/s-maxage` 与 `must-revalidate`/`stale-while-revalidate`，避免过时内容长尾污染。

四、扩展：HEAD 与弱标签策略对于目录索引或列表页，可提供 `HEAD` 路由快速探测并返回 ETag/Cache-Control，不携带响应体，降低探测带宽与耗时。弱标签可用于允许“轻微变更但视为未变”场景，需结合业务语义评估适配度。