Next.js 15 Range 断点下载与 Content-Range 路由实践

概览通过在 Route Handlers 中解析 `Range` 请求头，返回 `206 Partial Content` 与 `Content-Range`，可实现断点下载与续传。Edge Runtime 适合流式输出与低延迟传输。app/api/download/route.tsexport const runtime = 'edge'

const SIZE = 10 * 1024 * 1024 // 10MB 示例

export async function GET(req: Request) {

const range = req.headers.get('range')

let start = 0

let end = SIZE - 1

if (range) {

const m = /bytes=(\d+)-(\d+)?/.exec(range)

if (m) {

start = Number(m[1])

end = m[2] ? Number(m[2]) : Math.min(start + 1024 * 256 - 1, SIZE - 1) // 默认 256KB 分块

}

}

const chunkSize = end - start + 1

const stream = new ReadableStream({

start(controller) {

// 这里用随机字节模拟实际文件读取

const buf = new Uint8Array(chunkSize)

crypto.getRandomValues(buf)

controller.enqueue(buf)

controller.close()

},

})

const status = range ? 206 : 200

const headers: Record<string, string> = {

'Content-Type': 'application/octet-stream',

'Accept-Ranges': 'bytes',

'Content-Length': String(chunkSize),

}

if (range) {

headers['Content-Range'] = `bytes ${start}-${end}/${SIZE}`

}

return new Response(stream, { status, headers })

}

客户端续传async function fetchChunk(url: string, start: number) {

const res = await fetch(url, { headers: { Range: `bytes=${start}-` } })

const ab = await res.arrayBuffer()

return new Uint8Array(ab)

}

治理要点实际场景使用存储读取（Blob/文件系统/对象存储），并做边界与合法性校验。设置 `Accept-Ranges: bytes` 并正确返回 `Content-Range` 与 `206` 状态码。与鉴权协同，避免未授权下载；记录断点与进度以便恢复。验证与指标浏览器与客户端：断点续传可靠；大文件传输更稳定Next.js：15.0+；Edge Runtime：稳定