Effect 4.0 静态文件服务修复解析HttpStaticServer 忽略非 GET 请求的 Range 头【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本篇基于 Effect 仓库中的 changeset 变更记录深入剖析HttpStaticServer对 HTTPRange请求头的一项语义修复非 GET 请求一律忽略Range头。文章以该变更为主线结合 HttpStaticServer 源码 与两组测试用例完整梳理 Effect 静态文件服务中字节范围请求Byte Range的解析、响应与条件请求交互机制读者读完可掌握其实现原理、修复动机及可复现的验证方式。变更记录一条简短的 patch 说明仓库中的 changeset 变更文件 .changeset/pre/fix-static-head-range.md 内容如下--- effect: patch --- Ignore Range headers on non-GET requests in HttpStaticServer.这是一条典型的 Changesets 风格发布说明其中包含两个关键信息变更级别effect: patch表示这是对effect包的一次补丁级patch修复不涉及 API 破坏也不新增功能仅修正行为缺陷变更内容HttpStaticServer不再响应非 GET 请求如POST、HEAD、PUT、DELETE携带的Range头。这条记录本身只有两行正文但它的背后是 Effect HTTP 模块中静态文件服务的一段完整逻辑。下面我们结合源码与测试把这次修复的技术细节完整展开。背景HttpStaticServer 与字节范围请求HttpStaticServer是 Effect 4.0 中用于托管静态文件的 HTTP 应用组件位于 packages/effect/src/unstable/http/HttpStaticServer.ts。根据其模块头注释它承担以下职责Serves static files for Effect HTTP applications.HttpStaticServerturns request paths into file responses under a configured root directory. It can be used as an application value or mounted onto anHttpRouter, and it handles index files, optional single-page application fallback, MIME type headers, cache-control headers,byte ranges, and conditional304 Not Modifiedresponses.即将请求路径映射为指定根目录下的文件响应支持首页文件index、可选 SPA 回退、MIME 类型头、Cache-Control头、**字节范围byte range**以及条件请求的304 Not Modified响应。字节范围请求是 HTTP/1.1 的标准能力RFC 9110 中定义客户端通过Range: bytesstart-end头请求资源的指定字节区间服务器以206 Partial Content响应并携带Content-Range头说明返回区间当区间无法满足时返回416 Range Not Satisfiable。这一机制是视频/音频流媒体断点续传、大文件分片下载、PDF 按页加载等场景的基础。修复核心只有 GET 才读取 Range 头本次修复在源码中的落点非常清晰位于 HttpStaticServer.ts 第 117 行 的serveFile内部const rangeHeader request.method GET ? request.headers[range] : undefined这一行在修复前的行为是直接读取request.headers[range]不区分请求方法修复后则仅在请求方法为GET时才读取Range头其余方法一律视为无范围请求。为什么这样做是正确且必要的依据 HTTP 语义Range头只在请求获取资源表示representation时有意义而GET正是取回表示的方法HEAD虽不返回实体但语义上等价于GET的响应头对于POST、PUT、DELETE等方法请求主体是提交的数据而非对资源的获取携带Range头在语义上不成立若服务端对非 GET 请求误响应206或按区间截断资源可能破坏方法语义甚至导致客户端解析到非预期的部分响应体引发数据完整性风险。因此忽略非 GET 请求上的Range头本质上是让静态文件服务严格遵循 HTTP 规范中Range 应用于 GET及 HEAD语义的约束避免对未知方法组合产生歧义行为。Range 处理全流程从解析到响应在确认rangeHeader取值之后serveFile的后续逻辑完整实现了字节范围请求的标准流程。为了理解这次修复在整个流程中的位置我们把它完整拆解如下均出自 HttpStaticServer.ts。第一步条件请求优先const shouldEvaluateConditionals request.headers[if-none-match] ! undefined || request.headers[if-modified-since] ! undefined if (shouldEvaluateConditionals) { fullResponse yield* getFullResponse() const conditionalResponse evaluateConditionalRequest(request, fullResponse) if (conditionalResponse ! undefined) { return conditionalResponse } }若请求携带If-None-Match或If-Modified-Since会先构造完整响应并评估条件命中缓存时返回304 Not Modified。测试 HttpStaticServerConditional.test.ts 中的matched If-None-Match takes precedence over Range用例验证了这一点同时携带If-None-Match: etag-value与Range: bytes1000-1001时响应为304且content-range与accept-ranges均为null——即条件请求命中时不会再进入范围分支该测试位于 第 241-261 行。第二步无 Range 头则返回完整文件if (rangeHeader undefined) { return yield* getFullResponse() }这正是本次修复的语义落点对于非 GET 请求rangeHeader恒为undefined因此直接返回200完整响应Range头被静默忽略。第三步解析 Range 并处理非法/不可满足区间const resolvedFileSize fileSize ?? (yield* handlePlatformError(request, fileSystem.stat(filePath))).size const parsedRange parseRange(rangeHeader, resolvedFileSize) if (parsedRange undefined) { return yield* getFullResponse() } if (parsedRange unsatisfiable) { return HttpServerResponse.empty({ status: 416, headers: { Content-Range: bytes */${resolvedFileSize} } }) }文件大小来自调用方传入的fileSize参数或通过fileSystem.stat动态获取。parseRange返回三种结果返回值含义服务端行为{ start, end }合法区间返回206 Partial Contentunsatisfiable区间不可满足返回416附Content-Range: bytes */sizeundefined头非法或无法解析忽略返回完整200响应parseRange函数第 315-377 行的解析规则必须以bytes开头大小写不敏感否则视为非法仅支持单个范围值中包含逗号多范围请求直接返回undefined支持三种形态bytesstart-end闭区间、bytesstart-起始点后到文件末尾、bytes-suffixLength末尾倒数 N 字节起始值大于等于文件大小、起始值大于结束值等情况返回unsatisfiable区间结束值超过文件大小时自动钳制到fileSize - 1数字解析采用BigInt以规避Number.MAX_SAFE_INTEGER精度问题。关于大整数边界HttpStaticServer.test.ts 中有专门用例bytes超过 MAX_SAFE_INTEGER-形式的起始值返回416第 184-195 行而结束值与后缀长度超过MAX_SAFE_INTEGER时则返回整文件作为206第 201-209 行并验证了保留非零起始值的同时钳制超大结束值的行为第 215-223 行。第四步构造 206 部分响应let response setFileHeaders( yield* handlePlatformError( request, platform.fileResponse(filePath, { status: 206, offset: parsedRange.start, bytesToRead: parsedRange.end - parsedRange.start BigInt(1) }) ), filePath ) response HttpServerResponse.setHeader( response, Content-Range, bytes ${parsedRange.start}-${parsedRange.end}/${resolvedFileSize} )合法的区间请求通过platform.fileResponse以status: 206、offset起始偏移与bytesToRead读取字节数下发并设置Content-Range: bytes start-end/size头。这里的setFileHeaders第 97-109 行同时设置了Content-Type按扩展名解析 MIME未知扩展名回退application/octet-stream与Accept-Ranges: bytes若配置了cacheControl还会附加Cache-Control。第五步HEAD 请求的兼容说明值得留意的是修复将Range读取限定为GETHEAD请求同样不会触发范围分支。由于HEAD语义上不返回实体只返回与GET相同的响应头直接走完整响应路径、不生成部分内容属于规范的保守处理避免对仅请求元数据的HEAD返回不完整的206语义。测试佐证行为被显式锁定Effect 仓库为本次修复提供了充分的测试保障主要分布在两个文件packages/platform/node/test/HttpStaticServer.test.ts —— 第 152-223 行集中覆盖 Range 请求的各类分支合法的bytes0-10、开区间bytes5-、后缀bytes-10、非法区间bytes100-200返回 416、畸形头bytesabc忽略并返回完整响应以及超出Number.MAX_SAFE_INTEGER的边界行为packages/platform/node/test/HttpStaticServerConditional.test.ts —— 覆盖If-None-Match、If-Modified-Since与 Range 的优先级关系第 241-261 行验证条件命中时 Range 被完全忽略。这些用例的断言包括状态码206/416/304/200、Content-Range的精确格式、Accept-Ranges与Content-Type等头的存在与否构成了对静态文件服务范围请求语义的完整回归保护。开发者后续在修改相关逻辑时可运行 Node 平台测试目录下的用例进行验证。实战意义与影响面作为patch级修复本次变更对所有使用HttpStaticServer的 Effect HTTP 应用透明生效语义更规范非 GET 请求携带Range头时不再产生歧义的部分响应服务端行为可预测对 GET 场景零影响合法的字节范围请求流媒体、分片下载等行为完全不变与条件请求正确协同If-None-Match命中时仍优先返回304不会错误地返回206部分内容。如果你在自己的应用中直接处理Range头也应遵循同样的原则仅对GET请求评估范围语义并将其置于条件请求If-None-Match/If-Modified-Since判定之后避免缓存命中与范围响应之间产生冲突。小结本次 changeset 记录虽短但对应的是HttpStaticServer中一行关键语义修正const rangeHeader request.method GET ? request.headers[range] : undefinedHttpStaticServer.ts 第 117 行。它让 Effect 的静态文件服务严格遵循 HTTP 规范——Range仅适用于获取资源的请求语义同时通过parseRange的完整解析与边界处理保障了合法范围请求的206/416行为不受影响。对于需要托管静态资源、支持流式或断点下载的 Effect HTTP 应用理解这一机制有助于排查与设计基于Range的下载功能。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 17:41:37 · 阅读 1.2k Effect 4.0 静态文件服务修复解析：HttpStaticServer 忽略非 GET 请求的 Range 头
Effect 4.0 静态文件服务修复解析HttpStaticServer 忽略非 GET 请求的 Range 头【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本篇基于 Effect 仓库中的 changeset 变更记录深入剖析HttpStaticServer对 HTTPRange请求头的一项语义修复非 GET 请求一律忽略Range头。文章以该变更为主线结合 HttpStaticServer 源码 与两组测试用例完整梳理 Effect 静态文件服务中字节范围请求Byte Range的解析、响应与条件请求交互机制读者读完可掌握其实现原理、修复动机及可复现的验证方式。变更记录一条简短的 patch 说明仓库中的 changeset 变更文件 .changeset/pre/fix-static-head-range.md 内容如下--- effect: patch --- Ignore Range headers on non-GET requests in HttpStaticServer.这是一条典型的 Changesets 风格发布说明其中包含两个关键信息变更级别effect: patch表示这是对effect包的一次补丁级patch修复不涉及 API 破坏也不新增功能仅修正行为缺陷变更内容HttpStaticServer不再响应非 GET 请求如POST、HEAD、PUT、DELETE携带的Range头。这条记录本身只有两行正文但它的背后是 Effect HTTP 模块中静态文件服务的一段完整逻辑。下面我们结合源码与测试把这次修复的技术细节完整展开。背景HttpStaticServer 与字节范围请求HttpStaticServer是 Effect 4.0 中用于托管静态文件的 HTTP 应用组件位于 packages/effect/src/unstable/http/HttpStaticServer.ts。根据其模块头注释它承担以下职责Serves static files for Effect HTTP applications.HttpStaticServerturns request paths into file responses under a configured root directory. It can be used as an application value or mounted onto anHttpRouter, and it handles index files, optional single-page application fallback, MIME type headers, cache-control headers,byte ranges, and conditional304 Not Modifiedresponses.即将请求路径映射为指定根目录下的文件响应支持首页文件index、可选 SPA 回退、MIME 类型头、Cache-Control头、**字节范围byte range**以及条件请求的304 Not Modified响应。字节范围请求是 HTTP/1.1 的标准能力RFC 9110 中定义客户端通过Range: bytesstart-end头请求资源的指定字节区间服务器以206 Partial Content响应并携带Content-Range头说明返回区间当区间无法满足时返回416 Range Not Satisfiable。这一机制是视频/音频流媒体断点续传、大文件分片下载、PDF 按页加载等场景的基础。修复核心只有 GET 才读取 Range 头本次修复在源码中的落点非常清晰位于 HttpStaticServer.ts 第 117 行 的serveFile内部const rangeHeader request.method GET ? request.headers[range] : undefined这一行在修复前的行为是直接读取request.headers[range]不区分请求方法修复后则仅在请求方法为GET时才读取Range头其余方法一律视为无范围请求。为什么这样做是正确且必要的依据 HTTP 语义Range头只在请求获取资源表示representation时有意义而GET正是取回表示的方法HEAD虽不返回实体但语义上等价于GET的响应头对于POST、PUT、DELETE等方法请求主体是提交的数据而非对资源的获取携带Range头在语义上不成立若服务端对非 GET 请求误响应206或按区间截断资源可能破坏方法语义甚至导致客户端解析到非预期的部分响应体引发数据完整性风险。因此忽略非 GET 请求上的Range头本质上是让静态文件服务严格遵循 HTTP 规范中Range 应用于 GET及 HEAD语义的约束避免对未知方法组合产生歧义行为。Range 处理全流程从解析到响应在确认rangeHeader取值之后serveFile的后续逻辑完整实现了字节范围请求的标准流程。为了理解这次修复在整个流程中的位置我们把它完整拆解如下均出自 HttpStaticServer.ts。第一步条件请求优先const shouldEvaluateConditionals request.headers[if-none-match] ! undefined || request.headers[if-modified-since] ! undefined if (shouldEvaluateConditionals) { fullResponse yield* getFullResponse() const conditionalResponse evaluateConditionalRequest(request, fullResponse) if (conditionalResponse ! undefined) { return conditionalResponse } }若请求携带If-None-Match或If-Modified-Since会先构造完整响应并评估条件命中缓存时返回304 Not Modified。测试 HttpStaticServerConditional.test.ts 中的matched If-None-Match takes precedence over Range用例验证了这一点同时携带If-None-Match: etag-value与Range: bytes1000-1001时响应为304且content-range与accept-ranges均为null——即条件请求命中时不会再进入范围分支该测试位于 第 241-261 行。第二步无 Range 头则返回完整文件if (rangeHeader undefined) { return yield* getFullResponse() }这正是本次修复的语义落点对于非 GET 请求rangeHeader恒为undefined因此直接返回200完整响应Range头被静默忽略。第三步解析 Range 并处理非法/不可满足区间const resolvedFileSize fileSize ?? (yield* handlePlatformError(request, fileSystem.stat(filePath))).size const parsedRange parseRange(rangeHeader, resolvedFileSize) if (parsedRange undefined) { return yield* getFullResponse() } if (parsedRange unsatisfiable) { return HttpServerResponse.empty({ status: 416, headers: { Content-Range: bytes */${resolvedFileSize} } }) }文件大小来自调用方传入的fileSize参数或通过fileSystem.stat动态获取。parseRange返回三种结果返回值含义服务端行为{ start, end }合法区间返回206 Partial Contentunsatisfiable区间不可满足返回416附Content-Range: bytes */sizeundefined头非法或无法解析忽略返回完整200响应parseRange函数第 315-377 行的解析规则必须以bytes开头大小写不敏感否则视为非法仅支持单个范围值中包含逗号多范围请求直接返回undefined支持三种形态bytesstart-end闭区间、bytesstart-起始点后到文件末尾、bytes-suffixLength末尾倒数 N 字节起始值大于等于文件大小、起始值大于结束值等情况返回unsatisfiable区间结束值超过文件大小时自动钳制到fileSize - 1数字解析采用BigInt以规避Number.MAX_SAFE_INTEGER精度问题。关于大整数边界HttpStaticServer.test.ts 中有专门用例bytes超过 MAX_SAFE_INTEGER-形式的起始值返回416第 184-195 行而结束值与后缀长度超过MAX_SAFE_INTEGER时则返回整文件作为206第 201-209 行并验证了保留非零起始值的同时钳制超大结束值的行为第 215-223 行。第四步构造 206 部分响应let response setFileHeaders( yield* handlePlatformError( request, platform.fileResponse(filePath, { status: 206, offset: parsedRange.start, bytesToRead: parsedRange.end - parsedRange.start BigInt(1) }) ), filePath ) response HttpServerResponse.setHeader( response, Content-Range, bytes ${parsedRange.start}-${parsedRange.end}/${resolvedFileSize} )合法的区间请求通过platform.fileResponse以status: 206、offset起始偏移与bytesToRead读取字节数下发并设置Content-Range: bytes start-end/size头。这里的setFileHeaders第 97-109 行同时设置了Content-Type按扩展名解析 MIME未知扩展名回退application/octet-stream与Accept-Ranges: bytes若配置了cacheControl还会附加Cache-Control。第五步HEAD 请求的兼容说明值得留意的是修复将Range读取限定为GETHEAD请求同样不会触发范围分支。由于HEAD语义上不返回实体只返回与GET相同的响应头直接走完整响应路径、不生成部分内容属于规范的保守处理避免对仅请求元数据的HEAD返回不完整的206语义。测试佐证行为被显式锁定Effect 仓库为本次修复提供了充分的测试保障主要分布在两个文件packages/platform/node/test/HttpStaticServer.test.ts —— 第 152-223 行集中覆盖 Range 请求的各类分支合法的bytes0-10、开区间bytes5-、后缀bytes-10、非法区间bytes100-200返回 416、畸形头bytesabc忽略并返回完整响应以及超出Number.MAX_SAFE_INTEGER的边界行为packages/platform/node/test/HttpStaticServerConditional.test.ts —— 覆盖If-None-Match、If-Modified-Since与 Range 的优先级关系第 241-261 行验证条件命中时 Range 被完全忽略。这些用例的断言包括状态码206/416/304/200、Content-Range的精确格式、Accept-Ranges与Content-Type等头的存在与否构成了对静态文件服务范围请求语义的完整回归保护。开发者后续在修改相关逻辑时可运行 Node 平台测试目录下的用例进行验证。实战意义与影响面作为patch级修复本次变更对所有使用HttpStaticServer的 Effect HTTP 应用透明生效语义更规范非 GET 请求携带Range头时不再产生歧义的部分响应服务端行为可预测对 GET 场景零影响合法的字节范围请求流媒体、分片下载等行为完全不变与条件请求正确协同If-None-Match命中时仍优先返回304不会错误地返回206部分内容。如果你在自己的应用中直接处理Range头也应遵循同样的原则仅对GET请求评估范围语义并将其置于条件请求If-None-Match/If-Modified-Since判定之后避免缓存命中与范围响应之间产生冲突。小结本次 changeset 记录虽短但对应的是HttpStaticServer中一行关键语义修正const rangeHeader request.method GET ? request.headers[range] : undefinedHttpStaticServer.ts 第 117 行。它让 Effect 的静态文件服务严格遵循 HTTP 规范——Range仅适用于获取资源的请求语义同时通过parseRange的完整解析与边界处理保障了合法范围请求的206/416行为不受影响。对于需要托管静态资源、支持流式或断点下载的 Effect HTTP 应用理解这一机制有助于排查与设计基于Range的下载功能。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考