manifest 的 scope 决定了你的 PWA 安装边界

为何现在关系重大：

• 用户在社交、邮件、聊天中发送并打开到你的站点的链接。若链接落在 scope 内，浏览器会保持应用式界面并隐藏地址栏；若落在 scope 外，浏览器会重新暴露地址栏以提示“你跳到了这个站点的其它页面”，这会削弱已安装应用的体验。
• 一些产品需要在不同字段拥有多个应用（例如“管理端 PWA”与“客户端 PWA”）。多个 manifest 之间的 scope 冲突会导致“N+1 次安装”摩擦：浏览器可能弹出第二次安装提示或降低可安装性。
• share_target 与 shortcuts 等能力只在应用的 scope 范围内生效。

scope 对已安装体验的影响

“域内”与“域外”

• 域内路径以 scope 字符串开头（如 /app/ 匹配 /app/、/app/page.html、/app/dashboard/）。浏览器会抑制浏览器控件。
• 域外路径（例如当 scope 为 /app/ 时的 /、/blog/）会再次显示地址栏，让用户知道自己离开了“应用部分”。
• scope 不会阻止到域外 URL 的导航；浏览器允许在同一个上下文中访问域外页面，但展示方式会改变。

深度链接

• 当分享一条深度链接（例如 https://example.com/app/order/123）且 /app/ 为你的 scope 时，已安装用户会在应用内打开它，不显示地址栏。
• 若深度链接为 https://example.com/blog 而 scope 为 /app/，已安装用户看到地址栏出现，因为已进入域外路径。

受 scope 强绑定的能力

• share_target：编码的目标 URL 必须为注册它们的 manifest 的 scope 域内 URL。对于已安装时的调用，域外的分享目标 URL 不会被使用。
• shortcuts：所有快捷方式的 URL 必须位于同一 manifest 中定义的 scope 域内。如果某个快捷方式 URL 超出边界，浏览器会忽略该快捷方式或拒绝加载 manifest。

scope 的决策判定框架

| 决策问题 | 建议行为 | 理由 | |---------|---------|-----| | 想要一个覆盖整个站点的统一 PWA 吗？ | manifest 中省略 scope（隐式默认）或将其置为源的根路径（/）。 | 降低 N+1 安装风险；任何深度链接皆“进入应用”。 | | 需要按产品字段/管理员 vs 客户端分别创建 PWA 吗？ | 为每个 manifest 使用不同的 scope；确保每个 start_url 都在各自的 scope 范围内。 | 每个安装都指向独立的“应用上下文”；用户可以同时安装两者。 | | 是否使用 share_target 或 shortcuts 作为关键能力？| 包含 scope 并验证所有目标 URL 与快捷方式 URL 均为域内 URL。 | 这些能力相对于清单是有界的；域外的 URL 无法在已安装时正确触发。 | | 站点是否有不属于核心应用的全局营销或博客页面？ | 把 scope 设置为核心应用路径（如 /app/），并将营销置于域外路径；添加清晰的导航指示回到应用内部。 | 用户仍可通过明显不同入口访问营销内容，并预期 URL 栏出现。 | | 是否把基于 URL 的状态或深度链接作为主要用户流程？ | 将 scope 与所有可深度链接路径的公共最长前缀对齐，并验证深度链接落在域内。 | 保证深度链接的应用内展示，减少“地址栏再现”的体验问题。 |

实践清单

• [ ] 决定是统一 PWA（省略 scope 或设置为 /）还是按字段设置 PWA（使用显式 scope，如 /app/）。
• [ ] 若在 manifest 中声明 scope（如 /app/ 或 https://example.com/app/），建议以 / 结尾，避免前缀匹配（prefix-matching）到意外路径（例如 /prefix 也会匹配 /prefix-of/）。
• [ ] 验证 start_url 是 scope 的子路径。若 start_url 在 scope 之外，浏览器会改用基于 start_url 的回退 scope，忽略你声明的值。
• [ ] 确保所有 share_target 的 URL 与所有 shortcuts.url 都在 scope 域内。
• [ ] 测试来自分享与社交的深度链接：在已安装 PWA 环境中打开，确认域内链接的地址栏保持隐藏。
• [ ] 若需要多个 PWA（如管理端 vs 客户端），确保每个 manifest 拥有唯一 scope，且 start_url 在该 scope 内，避免共用同一个 manifest 引起注册冲突。
• [ ] 对 manifest 做合法 JSON 检查；非法 scope 类型或格式错误的 URL 会回退到默认行为（从 start_url 推导）。

开发者清单

• [ ] 仅在需要边界时添加 "scope"；否则省略它，以使用基于 start_url 的回退。
• [ ] 设置 scope 时首选绝对或同源 URL；使用相对 URL 时，需相对于 manifest 自身路径来解析。
• [ ] 在 CI/CD 中加入 manifest lint 步骤，检查：scope 以 / 结尾，且 start_url 是 scope 的子路径。
• [ ] 对 manifest 中的每个 share_target 条目，检查其 URL 以 scope 为前缀（或等于 start_url，若你只想要单一活动的分享入口）。
• [ ] 对每个 shortcuts 条目，验证 url 在 scope 域内。
• [ ] 新增可深度链接路径时，要么更新 scope，要么为分离的产品字段创建新 manifest；不要用同一 manifest 包含割裂的产品字段。
• [ ] 在客户端遥测中记录“域外导航”，以发现能力或覆盖缺口（例如用户频繁打开域外链接）。

要避免什么

• 不要把 scope 设置为不包含 start_url 的值；浏览器会忽略 scope 并使用回退值。
• 不要使用非结尾式、不明确的 scope（如 /prefix 而非 /prefix/），否则会匹配意外路径（例如 /prefix-of/index.html）。
• 不要在多个“应用”（管理端 vs 客户端）之间共用同一个 manifest；这会带来安装性混淆与 N+1 次安装提示。
• 不要在声称“全应用内体验”的同时在声明的 scope 之外放置支持/营销页面；深度链接仍会暴露地址栏。
• 不要用暗黑模式提示在域外页面强行安装；浏览器仍可能要求显式用户动作，且用户信任会受损。

这对可安装性与信任意味着什么

正确范围的 manifest 会让深度链接感觉原生，并保证分享与快捷方式可靠地“在应用内”运作。当用户从社交媒体或邮件分享/点击一条应用链接且看到熟悉的应用式界面（没有地址栏）时，他们会确认“这条链接属于我已安装的应用”，从而增强信任。反过来说，scope 不匹配或在分享入口和快捷方式期望的地方缺少 scope，会令这些能力“回退”到浏览器网页体验，感觉不一致且 Less integrated。

提供清晰稳定的 scope 也有助于应用商店等市场的评审员与商店验证 PWA 的身份与边界。当你把 manifest 提交给市场时，scope 定义了他们“预览”的已安装应用边界；scope、shortcuts 与 share_target 之间的对齐会让你的应用更好解释、评审员与用户更容易信任。

下一步

• 运行一个 scope 审计脚本（例如一个 JSON Schema 或 lint，检查 scope 包含 start_url 且以 / 结尾）。
• 验证所有 share_target URL 与 shortcuts.url 均在 scope 范围内。
• 为深度链接增加一次冒烟测试：使用已安装 PWA；打开一条域内深度链接；确认地址栏保持隐藏。
• 若计划按产品字段制作多个 PWA，请创建独立的 manifest，使用不同 scope 与唯一的 start_urls；避免用单一 manifest 声称多个像不同应用的字段。
• 在开发者指南中标记有意的域外路径，让后续贡献者理解产品的应用边界。
• 优化应用的商店列表（如截图）以突出受限能力（快捷方式、分享动作），强化它们在相同 scope 下“在应用内有效”的认知，这正是市场评审所验证的边界。