Serving a file from a Service Worker without breaking "Save Image As..."

在渐进式Web应用（PWA）开发中，Service Worker作为浏览器与网络之间的代理，能够拦截网络请求、缓存资源、实现离线访问，极大地提升了用户体验。然而，一个看似简单却常被忽略的细节——当Service Worker从缓存中直接提供图片、PDF等文件时，用户右键点击“另存为...”或“保存图片...”的功能可能会意外失效。这一问题困扰着许多开发者，尤其是当应用需要保留用户下载原文件的能力时。本文将从技术原理出发，剖析问题根源，并给出有效的解决方案。

问题的本质：Service Worker如何“破坏”保存操作？

在传统网页中，当用户对一张图片右键点击“另存为...”，浏览器会直接向服务器发起资源请求，服务器返回的文件流含有正确的Content-Disposition头（例如attachment; filename="image.png"），浏览器据此触发下载对话框。但一旦引入Service Worker，所有从该作用域发出的请求都会先经过Worker的fetch事件处理程序。如果Worker简单地拦截请求并返回一个基于Response构造的Blob（例如从Cache API中读取），那么这个响应的Content-Disposition头通常不会被正确设置，或者根本不存在。

更关键的是，浏览器在触发“另存为”时，会检查响应是否具有可下载的“附件”语义。如果Content-Disposition被设置为inline（默认值）或者缺失，浏览器可能不会弹出保存对话框，而是直接尝试在浏览器内打开文件（如预览图片）。用户看到的将是“图片已加载”而非“下载”选项。此外，如果Service Worker返回的响应缺少必要的CORS头或Content-Type与实际文件不匹配，也可能导致保存功能静默失败。

为什么必须修复？用户体验与合规需求

对于以媒体内容为主的网站（如在线画廊、文档预览平台），保存图片/文件是核心交互。用户期望右键保存功能在任何网络状态下（包括离线）都能正常工作。如果Service Worker破坏了这一功能，用户可能误以为网站有缺陷，甚至怀疑文件权限问题。从技术合规角度，某些行业（如设计素材库、文档管理）要求用户能够合法下载原始文件，错误的实现可能引发法律风险。

解决方案：在Service Worker中正确构建响应

修复的关键是：当Service Worker提供文件响应时，明确设置Content-Disposition头和相关的HTTP头信息。以下是一个经过验证的实现思路。

1. 在缓存时保留原始响应头

最佳实践是在将资源存入Cache时，尽量保留原始服务器的响应头。例如，使用Cache API的put方法存储完整的Response对象：

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cachedResponse) => {
      if (cachedResponse) {
        // 直接返回缓存的响应（包含原始头信息）
        return cachedResponse;
      }
      return fetch(event.request).then((response) => {
        // 克隆响应并存入缓存，保留头
        const clonedResponse = response.clone();
        caches.open('my-cache').then((cache) => {
          cache.put(event.request, clonedResponse);
        });
        return response;
      });
    })
  );
});

2. 如果无法保留原始头，手动设置关键头

当无法从缓存中获取原始头（例如，资源由其他流生成），你需要在Response构造函数中手动添加头。特别是Content-Disposition：

async function serveImage(request) {
  const url = new URL(request.url);
  const filename = url.pathname.split('/').pop(); // 提取文件名

  const imageData = await getImageFromSomewhere(url); // 获得Blob
  const headers = new Headers({
    'Content-Type': imageData.type || 'application/octet-stream',
    'Content-Disposition': `attachment; filename="${filename}"`,
    'Content-Length': imageData.size.toString(),
  });

  return new Response(imageData, { headers });
}

3. 区分资源类型：内联与附件

并非所有资源都需要强制保存。对于HTML、CSS等静态资源，应保持inline（默认）。这里可以根据请求的Accept头或路径后缀进行判断。技巧：对图片请求，通常用户希望通过右键保存，所以对于<img>标签发出的请求（Sec-Fetch-Dest: image），将Content-Disposition设为inline反而会导致浏览器直接预览，没问题；只有用户主动触发“另存为”时，浏览器才会根据头决定行为。实际上，只要响应头中包含Content-Disposition: attachment，无论是图片还是其他文件，浏览器都会弹出下载对话框。因此，如果你希望所有通过Service Worker提供的图片都支持右键保存，统一设置attachment即可。

但请注意：这会改变浏览器的默认行为——原本“在新标签页打开图片”会变成下载。需要权衡，或者通过用户点击下载按钮时设置特殊参数来区分。

4. 为“保存链接为”场景提供支持

当用户右键点击链接（非直接图片）选择“保存链接为...”时，Service Worker需要返回带有Content-Disposition: attachment的响应。更稳妥的做法是在服务端就已经设置好，Service Worker仅传递。如必须动态生成，确保在fetch事件中判断event.request.mode和event.request.destination：'document'或'image'等。

最佳实践与注意事项

不要盲目设置所有资源为attachment：HTML、JS、CSS等文件如果被强制下载，页面将无法渲染。
注意跨域问题：如果资源来自不同域，Service Worker中构造的响应必须设置CORS头（Access-Control-Allow-Origin: *），否则浏览器可能拒绝保存。
测试不同浏览器：Chrome、Firefox、Safari对Content-Disposition的处理略有差异。例如，Safari在离线模式下如果响应头缺少Content-Length可能不显示下载进度。
回退策略：当Service Worker无法提供合适响应时，应允许请求回退到网络，避免强制返回错误数据。

总结

Service Worker为Web应用带来了离线能力，但同时也引入了新的陷阱——破坏“保存图片”等标准用户操作。通过正确设置Content-Disposition头和复制原始响应头，开发者可以轻松恢复这一功能。核心原则是：尊重用户的控制权，在提供缓存资源的同时，确保浏览器能够识别下载意图。随着PWA的普及，类似细节将成为衡量Web应用质量的重要指标。希望本文能帮助你构建更健壮的用户体验。

Serving a file from a Service Worker without breaking &quot;Save Image As...&quot;