File association lets PWAs appear like native apps in OS file pickers

为什么文件关联对 PWA 原生感很重要

操作系统上的文件通常与特定应用关联——用户单击文件时，OS 启动相应应用并传递文件。HTML 文件在浏览器打开，文本文件在文本编辑器，视频文件在视频播放器。

PWA 也能参与这一机制。用户单击特定类型文件时，PWA 可能被启动来处理它。这意味着：

• 原生发现性：你的 PWA 出现在"打开方式"菜单中，与原生应用并列
• 工作流整合：用户可以直接从文件管理器启动 PWA 来完成工作（如图像编辑、文档转换）
• 安装价值：文件关联让安装 PWA 变成可感知的工具价值

MDN 文档明确指出，目前此功能仅限 Chromium 浏览器，且仅限桌面操作系统。这是关键限制。

如何实施文件关联

步骤 1：在 manifest 中声明支持

使用 file_handlers 成员声明可处理的文件类型：

{
  "name": "Image Editor PWA",
  "icons": [...],
  "start_url": "/",
  "display": "standalone",
  "file_handlers": [
    {
      "action": "/editor",
      "accept": {
        "image/jpeg": [".jpg", ".jpeg"],
        "image/png": [".png"],
        "image/webp": [".webp"]
      },
      "name": "Open in Image Editor", // 可选，显示在 OS 菜单中
      "icons": ["/icons/editor-handler-96.png"] // 可选，可选性用于 OS 菜单
    }
  ]
}

关键属性：

• action：用户打开文件时导航到的 URL，必须在 PWA scope 内
• accept：对象键是 MIME 类型，值是支持的文件扩展名数组
• name（可选）：显示在 OS"打开方式"菜单中的名称
• icons（可选）：用于 OS 菜单的图标数组

步骤 2：处理传入的文件

使用 LaunchQueue 接口：

if ('launchQueue' in window) {
  launchQueue.setConsumer(async (launchParams) => {
    // launchParams.files 是 FileSystemHandle 数组
    for (const fileHandle of launchParams.files) {
      const file = await fileHandle.getFile();

      // 根据 MIME 类型决定如何处理
      if (file.type.startsWith('image/')) {
        previewImage(file);
      } else if (file.type === 'application/pdf') {
        renderPDF(file);
      }
    }
  });
}

关键 API：

• window.launchQueue：全局属性，仅 Chromium 桌面支持
• launchQueue.setConsumer(callback)：设置回调函数接收传入文件
• launchParams.files：FileSystemHandle[]，每个代表一个传入文件
• fileHandle.getFile()：异步获取 File 对象

步骤 3：处理权限和用户确认

首次请求时，浏览器会显示确认对话框请求用户允许 PWA 处理文件。用户可设置默认应用。

macOS 上的默认应用配置：右键文件 →"显示简介"（Get Info）→"打开方式"（Open with）。

实施检查清单

在产品化前，确认以下事项：

技术准备

• [ ] 站点使用 HTTPS（硬性要求）
• [ ] PWA 已安装为桌面应用（必需）
• [ ] file_handlers 的 action URL 在 PWA scope 内
• [ ] 检测 launchQueue 存在性，支持优雅降级

MIME 类型兼容性

• [ ] 使用标准 MIME 类型（如 image/jpeg、application/pdf、text/plain）
• [ ] 避免使用模糊或未注册的 MIME 类型
• [ ] 清晰说明每个 MIME 类型用途
• [ ] 扩展名与 MIME 类型一致（如 .jpg → image/jpeg）

用户体验

• [ ] 添加明确的"文件关联设置"说明
• [ ] 提供手动触发文件导入功能（fallback）
• [ ] 显示清晰的处理进度
• [ ] 提供处理失败时的友好的错误提示

隐私和安全

• [ ] 不会将文件内容上传服务器（除非用户明确授权）
• [ ] 不会存储文件路径或元数据（除非必要）
• [ ] 处理完成后清理临时 blob URL
• [ ] 用户可随时清除文件处理历史

对开发者意味着什么

产品机会

• 垂直工具 PWA：图像编辑器、CAD 工具、PDF 阅读器可成为默认文件处理器
• 工作流自动化：用户可直接从文件管理器启动 PWA 完成工作
• 安装转化：文件关联让安装可感知，提升安装率

技术债务

• 浏览器兼容性：仅支持 Chromium 桌面，需要为非用户提供明确提示
• Manifest 复杂度：多个 file_handlers 条目增加 manifest 维护成本
• 调试难度：文件关联难以直接在开发环境测试，需要使用真实 OS 文件系统

用户体验

• 首次启动困惑：用户可能不理解为何 PWA 突然出现，需要 UI 上下文
• 权限疲劳：频繁请求文件关联权限可能被用户拒绝
• 多应用冲突：多个 PWA 可能声明相同 MIME 类型，需要差异化竞争策略

平台差异

| 平台 | 支持情况 | 默认应用设置渠道 | |------|----------|-------------------| | Chrome Desktop | ✅ 完全支持 | 右键文件 → 打开方式 | | Edge Desktop | ✅ 完全支持 | 右键文件 → 打开方式 | | Safari Desktop | ❌ 不支持 | N/A | | Firefox Desktop | ❌ 不支持 | N/A | | Chrome Android | ❌ 不支持 | N/A | | iOS Safari | ❌ 不支持 | N/A |

关键发现：文件关联功能目前仅限桌面，移动 PWA 无法利用此能力。

应用场景决策框架

| 场景 | 推荐使用文件关联 | 不使用文件关联 | |------|---------------------|---------------| | 图像编辑器 PWA | ✅ 高度匹配 | ⚠️ 降低工具感 | | 文档转换工具 | ✅ 工作流整合 | ✅ 改用文件上传表单 | | PDF 阅读器 | ✅ 替代原生应用 | N/A（这是核心功能） | | 内容展示应用 | ⚠️ 可选性功能 | ✅ 改用拖放上传 | | 社交/聊天应用 | ❌ 无关场景 | ✅ 不涉及文件处理 | | 游戏 PWA | ❌ 无关场景 | ✅ 游戏不处理外部文件 |

下一步

1. 需求审查：确定你的 PWA 真的需要作为文件处理器，还是可以通过文件上传表单满足
2. 原型开发：先在单一 MIME 类型上实现，验证效果
3. 跨平台测试：在 Windows、macOS、Linux 上测试默认应用设置流程
4. 用户反馈：收集用户对"作为默认文件处理器"的反馈，调整产品方向

文件关联让 PWA 从"网页"变成"工具"。支持少数特定文件类型能为用户带来明显价值，贪多求全可能适得其反。