无缝 PWA 来源迁移：更改网域而不损失用户

Dibyajyoti Pal
Dibyajyoti Pal
LinkedIn
Dan Murphy
Dan Murphy
X LinkedIn
Marijn Kruisselbrink
Marijn Kruisselbrink
LinkedIn

Published: June 3, 2026

渐进式 Web 应用 (PWA) 通过提供类似应用的体验彻底改变了 Web。不过，PWA 的一大优势也一直是一个持续存在的挑战：应用身份与网站源紧密相关。

如需更改品牌或重组架构（例如，从 www.example.com/social 迁移到 social.example.com），您会面临一个令人痛苦的两难境地。 无法“移动”已安装的 PWA。用户不得不手动卸载旧应用，然后找到新应用的安装按钮。

PWA 团队很高兴在 Chrome 150 中推出 PWA 来源迁移 。 借助这项新的平台功能，您可以将已安装的 PWA 无缝迁移到新的同网站来源，最大限度地减少对用户的干扰，同时仍能让用户充分了解情况。

来源迁移的功能

您可以修改网站架构，而不会破坏用户体验：

  • 技术架构自由： 更改应用的子网域或路径。
  • 修复 拆分应用 状态： 解决在没有稳定 ID 的情况下更改 start_url 意外创建重复应用 安装的问题。

用户可以通过简单的更新对话框迁移应用。他们会以与 标准应用更新类似的方式获知 迁移情况。只需点击一下，旧应用就会被卸载，新应用就会被安装并启动。

如何迁移 PWA

如需迁移 PWA，请按照以下步骤操作。本文的其余部分将详细介绍这些步骤：

  1. 部署握手：
    • 将 migrate_from 添加到新应用。
    • 将 allow_migration 字段添加到旧来源的 /.well-known/web-app-origin-association 文件中。
  2. 选择行为： suggest（或空）可避免中断用户，这在初始发布期间可能很有用。如果用户无法继续使用旧网址，force 会阻止用户并要求迁移。
  3. 让旧应用保持最新状态： 如果旧网站重定向到新网站，请使用 migrate_from 块中的 install_url 属性，以确保浏览器仍能找到旧清单以进行潜在更新。
  4. 在目标清单中实现 id： Chrome 要求 目标应用清单包含 id 字段。这可确保应用 不会因 在没有设置 id 的情况下更改 start_url 而犯创建 拆分应用 的常见错误。

双向握手：工作原理

为确保安全并防止恶意接管，迁移需要旧来源和新来源之间进行安全握手。此握手可确保两个网站都由同一实体控制。

第 1 步：新应用声明前身（必需）

将 migrate_from 字段添加到 新 应用的 Web 应用清单中。

// Manifest at https://fileman.google.com/manifest.json
{
  "name": "File Manager",
  "id": "/files/",
  "start_url": "/files/index.html",
  ....
  "migrate_from": [
    "https://drive.google.com/"
  ]
}

第 2 步：旧来源确认迁移（必需）

为防止新网站单方面劫持旧应用，旧来源必须明确授权迁移。它通过 .well-known 配置文件执行此操作。

// File at https://drive.google.com/.well-known/web-app-origin-association
{
  "https://fileman.google.com/files/": {
    "allow_migration": true
  }
}

第 3 步：主动发出信号（可选）

如需触发更新，而无需等待用户访问新网站，请更新 旧 应用的清单以指向新应用。

// Manifest at https://drive.google.com/manifest.json
{
  "name": "Drive",
  "start_url": "/",
  "migrate_to": {
    "id": "https://fileman.google.com/files/",
    "install_url": "https://fileman.google.com/drive/installwebapp?usp=migrate"
  }
}

第 4 步：处理重定向（可选）

除了使用 migrate_to 字段之外，您还可以通过将旧应用网址重定向到新应用来发出迁移信号，并依赖 scope_extensions 使 范围外横幅不会显示在旧应用中。这意味着旧应用的清单永远不会被看到，因此永远无法更新。如需允许旧应用在应用迁移发生之前继续更新，请在 migrate_from 内设置 install_url，以告知浏览器要提取的网址，该网址仍附有旧清单，且没有重定向。

// Manifest at https://fileman.google.com/manifest.json
{
  "name": "File Manager",
  "id": "/files/",
  "start_url": "/files/index.html",
  ....
  "migrate_from": [
    {
      "id": "https://drive.google.com/",
      "install_url": "https://drive.google.com/drive/installwebapp?usp=migrate"
    }
  ]
}

大功告成！用户体验与 应用更新所用的用户体验类似， 用户会在应用窗口的右上角收到通知：

应用窗口显示有应用更新。该下拉菜单包含一个指向“查看应用更新”的链接。

点击查看应用更新 会显示以下用户体验（具体取决于清单中的更改内容）：

该对话框会要求用户查看徽标、名称和网址更新。

控制用户体验

您可以使用 behavior 标志选择迁移的激进程度：

  1. 建议（默认）： 用户会收到被动通知（例如，在应用菜单中）。他们可以选择更新、卸载应用或启动对话框来忽略迁移。
  2. 强制： 在下次启动应用时，用户会看到一个阻止对话框。他们必须更新到新来源或卸载应用（请参见以下屏幕截图）。

以下示例展示了如何设置此选项，

"migrate_from": [
  { 
    "id": "https://example.com/social/",
    "behavior": "force" // or suggest
  }
]

对话框会告知用户需要安装新版应用。

总结

借助 PWA 迁移功能，开发者可以继续构建现代化的灵活 Web 架构，而不会让用户掉队。