launch_handler是PWA启动行为控制的核心配置项，必须写在manifest.json顶层，支持client_mode（如focus-only、navigate-existing）以决定窗口聚焦或导航逻辑，并需与file_handlers等配合实现文件关联，缺一不可。
Chrome 119+ 开始，launch_handler 已成为 PWA 启动行为控制的核心配置项；它不替代 start_url，而是决定「用户点击桌面图标、从系统启动器打开、或通过文件/URL 关联触发时」PWA 如何响应 —— 配错就直接回退到默认 tab 切换逻辑，甚至静默失败。
launch_handler 必须写在 web app manifest 中，且仅支持特定值结构
它不是 JS API，也不是 HTML meta 标签，必须出现在 manifest.json 的顶层字段中。浏览器只认标准 JSON 结构，任何拼写错误（比如写成 launchHandler 或 launch-handlers）都会忽略该字段，降级为传统启动流程。
-
"launch_handler": {"client_mode": "focus-only"}：已有匹配窗口则聚焦，不新建；无则报错（白屏或 fallback 到start_url） -
"launch_handler": {"client_mode": "navigate-existing"}：已有窗口则导航到指定 URL（需配合files或url_pattern使用），否则新建窗口 -
"launch_handler": {"client_mode": "auto"}：Chrome 当前默认行为（等价于不设该字段），不推荐显式写
注意：client_mode: "focus-only" 在 iOS Safari 完全不生效，Android Chrome 119–123 对其支持也不稳定，生产环境慎用。
launch_handler + files 配合实现文件双击打开（如 .pdf、.md 关联）
仅靠 launch_handler 无法触发文件关联行为，必须同时满足三要素：manifest 中声明 files、注册 file_handlers、且用户已授予权限（首次打开文件时弹窗确认）。缺一不可。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
-
files是数组，每个对象需含accept（MIME 类型或扩展名）和name（仅用于调试标识） - 示例片段：
{ "launch_handler": { "client_mode": "navigate-existing" }, "file_handlers": [{ "action": "/open-file", "name": "Markdown Editor", "accept": {".md": ["text/markdown"]} }] } - 触发后，PWA 会以
/open-file?file=xxx形式导航，需在页面 JS 中读取location.search解析参数
常见错误：file_handlers.action 路径未在 scope 内，或未在 serviceworker 中拦截该请求并 claim client，导致导航失败回退到空白页。
launch_handler 不影响 URL Scheme 和 Intent 启动，但会干扰 PWA 安装检测
Android 上通过 intent:// 或自定义 scheme（如 myapp://open?id=123）启动 PWA 时，launch_handler 完全不参与；此时由 serviceworker 的 fetch 或 navigationPreload 控制。但它会影响 Chrome 的「是否显示安装横幅」判断：
- 若
launch_handler.client_mode === "focus-only"且当前无活跃客户端，Chrome 可能判定「无法可靠启动」，隐藏安装按钮 - Manifest 中存在
launch_handler但file_handlers或protocol_handlers缺失时，部分 Android 版本会拒绝将 PWA 添加到主屏幕 - 测试建议：用
chrome://apps查看 PWA 状态，或调用navigator.getInstalledRelatedApps()验证安装态
真正麻烦的是调试：Chrome DevTools 的 Application → Manifest 面板不会校验 launch_handler 语法，只有实际点击桌面图标才能暴露问题 —— 白屏、跳转到错误路径、或根本没反应，都是配置失效的典型信号。
