itty-router 中 CORS 与缓存响应冲突问题解析

问题背景

在使用 itty-router 5.0.16 版本开发 Workers 应用时，开发者发现当响应被缓存后，再配合使用 corsify 中间件会出现 "Can't modify immutable headers." 的错误。这个问题特别容易在以下场景复现：

1. 首次请求未被缓存时工作正常
2. 当响应被缓存后再次请求就会报错

问题根源分析

这个问题的本质在于 Workers 的缓存机制和响应头的不可变性：

1. 缓存响应的特性：当响应被缓存后，返回的 Response 对象会被标记为"不可变"(immutable)
2. corsify 的工作方式：corsify 中间件会尝试修改响应头来添加 CORS 相关的头部信息
3. 冲突产生：当 corsify 尝试修改已被缓存的不可变响应头时，就会抛出错误

解决方案演进

原始解决方案

开发者最初提出的临时解决方案是通过检查响应头中是否存在特定标记(如"server"头)来判断是否是缓存响应，如果是则跳过 corsify 处理：

function customCors(response, request){
    if(response.headers.has("server"))
        return response;
    return corsify(response.clone());
}

官方修复方案

在 itty-router 5.0.17 版本中，官方修复了这个问题。核心思路是在 corsify 内部处理时更加谨慎地处理响应头的修改，避免直接修改不可变头。

额外场景处理

除了缓存响应外，重定向响应(302)也可能出现类似问题。有开发者发现需要对重定向响应做特殊处理：

const wrappedCorsify = (response: Response, request?: Request): Response => {
    if (response?.status === 302) {
        return response;
    }
    return corsify(response, request);
};

最佳实践建议

1. 版本升级：确保使用 itty-router 5.0.17 或更高版本
2. 响应处理：
   • 对于需要缓存的响应，考虑在首次生成响应时就添加必要的 CORS 头
   • 避免对缓存响应进行二次修改
3. 特殊响应处理：
   • 重定向响应(302)通常不需要 CORS 头
   • 其他特殊状态码响应也需要考虑是否真的需要 CORS

技术原理深入

这个问题背后涉及几个重要的技术概念：

1. HTTP 缓存机制：边缘缓存会存储完整的响应对象
2. 响应不可变性：出于性能和安全考虑，缓存的响应被设计为不可变
3. CORS 实现原理：跨域资源共享依赖于特定的 HTTP 头部
4. 中间件执行顺序：在 itty-router 中，finally 钩子中的中间件会在路由处理后执行

理解这些底层原理有助于开发者更好地处理类似问题，并在设计应用架构时做出更合理的选择。