将 WebView2 运行时降级到早期版本

如果新版本的 WebView2 运行时在特定 WebView2 应用中引入了关键回归，则 IT 管理员可以使用策略将该应用的 WebView2 运行时降级到以前的版本DowngradeVersion，作为临时解决方案。

详细内容：

• 企业降级概述
  • 企业降级的工作原理
  • 存在企业降级的原因
  • 适用的 WebView2 应用
  • 策略配置和优先级
  • 核心设计原则
• 临时降级 WebView2 运行时
  • 选项 1：组策略 (GPO)
  • 选项 2：注册表编辑器 (regedit)
  • 重要说明
  • 流程：如何实现降级
• 降级 WebView2 运行时的限制
  • 版本限制
  • 范围限制
  • 共享用户数据文件夹 (UDF) 约束
• 降级 WebView2 运行时的风险
  • 安全风险
  • 数据完整性风险
  • 应用兼容性风险
  • 运营风险
• 对运行时降级进行测试和故障排除
  • 验证是否应用了运行时降级
    • 1. 检查版本控制文件夹
    • 2. 检查注册表策略
    • 3. 检查 BrowserExecutableFolder 重定向
  • 触发强制更新
  • 用于更深入故障排除的诊断工具
  • 常见问题和解决方法
• 删除 WebView2 运行时的降级
  • 选项 1：禁用组策略 (建议的)
  • 选项 2：通过注册表删除策略
  • 选项 3：自动到期
  • 还原后行为
• 升级和联系 WebView2 团队
• 另请参阅

企业降级概述

在企业中，IT 管理员可以使用策略将 WebView2 运行时降级到以前的版本，作为临时措施DowngradeVersion。 使用 Evergreen 运行时时，如果新的运行时版本引入了关键回归，则使用 WebView2 运行时的每个 WebView2 应用和每个 Windows 组件都可能会受到影响。 企业降级为 IT 管理员提供了一种短期缓解方法，以恢复受影响的工作效率。

该DowngradeVersion策略是一种受控版本降级功能，允许企业 IT 管理员临时还原特定的 WebView2 应用程序 (WebView2 应用) 在关键回归中断业务运营时通过组策略使用以前版本的 WebView2 运行时。 请参阅 Microsoft Edge WebView2 中的 DowngradeVersion - 策略。

常青分布模型意味着 WebView2 运行时与 Microsoft Edge 一起自动更新，因此 WebView2 应用始终在最新版本的 WebView2 运行时上运行，而无需手动干预。 Evergreen WebView2 运行时可确保 WebView2 应用自动获取安全修补程序和功能改进。 企业 IT 管理员无法卸载有影响的 WebView2 运行时更新。

WebView2 是一个浏览器控件，它允许 Windows 应用程序 (（如 Microsoft Teams、Outlook 和第三方企业软件) 使用 Microsoft Edge 呈现引擎嵌入 Web 内容。

企业降级的工作原理

1. IT 管理员发现新的 WebView2 运行时版本已破坏特定的 WebView2 应用。

2. IT 管理员设置一个组策略，指定对于此 WebView2 应用，使用特定的以前版本的 WebView2 运行时，而不是最新的 WebView2 运行时。

   仅支持相对于当前 Evergreen WebView2 运行时版本的 WebView2 运行时版本 N-1 或 N-2。 拒绝降级到早于版本 N-2 的 WebView2 运行时版本。

3. Edge 更新程序与当前 WebView2 运行时并 行 下载和安装旧的 WebView2 运行时版本。

4. WebView2 加载程序仅将目标 WebView2 应用重定向到较旧的 WebView2 运行时。

5. 设备上的所有其他 WebView2 应用将继续使用最新的 WebView2 运行时版本;它们不受降级的影响。

6. 当固定的版本不再位于 WebView2 运行时的两个最新的前一个版本中后，降级将自动过期。

存在企业降级的原因

企业降级是最后的恢复工具。 企业降级由企业 IT 管理员与 WebView2 应用所有者合作进行有针对性和时间约束和管理。 企业降级不是一种版本固定机制。

企业降级为受影响的特定 WebView2 应用提供临时的、管理员控制的版本降级，同时平台团队准备适当的修补程序。 只有在关键回归主动中断业务运营，并且没有其他缓解 (措施（如修补程序、功能标志或更新暂停）无法及时解决问题时，企业降级才应用作最后的恢复措施) 。 降级为平台团队提供了时间来发布适当的修复程序;降级不能替代提供适当的修复程序。

在任务关键型企业环境中，WebView2 运行时中的意外回归可能会停止业务工作流，而无需立即进行补救。 即使是短暂的中断也会导致收入损失、错过 SLA 和增加运营成本。 例如，任务关键型企业环境包括：

• 医疗保健系统
• 金融交易平台
• 零售销售点
• 政府服务

适用的 WebView2 应用

企业版 WebView2 运行时降级不会自动影响任何 WebView2 应用。 IT 管理员必须显式为特定 WebView2 应用配置DowngradeVersion策略。 然后，该策略仅应用于该特定 WebView2 应用。

可以针对以下类型的 WebView2 应用：

• 在企业托管的 Windows 设备上运行的任何 WebView2 Evergreen-Runtime 应用。

  • IT 管理员通过以下任一项来指定目标：

    • 应用程序用户模型 ID (AUMID) ，适用于打包/MSIX 应用。
    • 可执行文件名称 (如 ms-teams.exe) 。

  • 如果同一 WebView2 应用同时存在 AUMID 和 .exe 名称条目，则 AUMID 条目优先。

要查找名称， .exe 请执行以下操作：

1. 打开任务管理器，然后在左侧选择“ 详细信息”。

2. 找到正在运行的 WebView2 应用。

3. 检查 WebView2 应用的 “名称 ”列，如 ms-teams.exe Or olk.exe。

以下类型的 WebView2 应用不受策略影响 DowngradeVersion ：

• 策略中 DowngradeVersion 未指定的 WebView2 应用。

  • 此类应用将继续使用最新的 WebView2 常青运行时。

• 使用者设备或非托管设备上的 WebView2 应用。

• 使用应用捆绑的 WebView2 应用 (固定版本) WebView2 运行时。

策略配置和优先级

不支持HKEY_CURRENT_USER (HKCU) ;这是仅 (HKEY_LOCAL_MACHINE (HKLM) ) 的计算机级企业策略。

位置	路径
组策略 (推荐)	计算机配置>管理模板>Microsoft Edge WebView2>配置每应用程序 WebView2 降级版本
注册表	HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion

存在多个策略时的优先级 (从最高到最低) ：

1. DowngradeVersion 策略 — 始终胜出。

2. BrowserExecutableFolder — 如果由 IT 管理员独立设置。

3. 默认常青运行时 - 最低。

如果 and BrowserExecutableFolder 都是DowngradeVersion独立配置的，DowngradeVersion则具有优先权并替代BrowserExecutableFolder重定向。

核心设计原则

• 企业 IT 管理员驱动：只有 IT 管理员才能通过组策略启动降级。 开发人员和最终用户无法触发它。

• 更新程序服务合规性： Edge 更新程序将根据需要下载所需的版本，并继续对所有其他应用进行正常更新。

• 自动到期： 只要降级版本位于 N-1 或 N-2) (两个最新的前一个版本内，降级版本就仍然有效。 在降级版本之外发布两个后续新主要版本后，降级将过期，应用会自动还原到最新的运行时。 Microsoft 建议 IT 管理员应在过时策略自动过期后将其删除。

• 按应用定位： 降级按应用应用，而不是设备全体应用。 必须在策略中单独指定每个 WebView2 应用。

临时降级 WebView2 运行时

更新策略模板

更新策略模板：

1. 转到“下载并部署 Microsoft Edge 商业版”。

2. 在“ 下载最新版本 ”部分中，单击以下按钮之一：

   • Windows
   • macOS
   • Linux

3. 单击 “下载”...策略 链接，例如：

   • 下载 Windows 64 位策略
   • 下载 Windows 32 位策略
   • 下载 Windows ARM64 策略
   • 下载 macOS 通用策略
   • 下载 Linux (.rpm) 策略
   • 下载Linux (.deb) 策略

   “ 下载 Microsoft Edge 策略文件 ”对话框随即打开。

4. 单击 “接受并下载 ”按钮。

   下载了一个文件，例如 MicrosoftEdgePolicyTemplates.cab。

5. 在 Microsoft Edge 中，选择“设置”和“更多 (...) ”，选择“下载”，然后对于已下载的文件，单击“打开包含文件夹”。

   在 Windows 上，文件资源管理器将打开，并选中该文件MicrosoftEdgePolicyTemplates.cab。

6. 右键单击 MicrosoftEdgePolicyTemplates.cab，然后选择“ 打开”。

   MicrosoftEdgePolicyTemplates.zip 的位置。

7. 右键单击 MicrosoftEdgePolicyTemplates.zip，然后选择 “提取”。

   “ 选择目标 ”对话框将打开。

8. 选择目录，例如 C:\Users\local-account\Downloads，然后单击“ 提取 ”按钮。

   已创建一个文件夹，例如： C:\Users\local-account\Downloads\MicrosoftEdgePolicyTemplates.zip

9. 在左侧选择 MicrosoftEdgePolicyTemplates.zip，然后在右侧打开 /windows/ 目录。

   列出了文件夹/adm//admx/。

10. 将文件夹/adm//admx/复制到目录/PolicyDefinitions/中。 例如，对于 Windows，将 and /admx/ 文件夹复制/adm/到 C:\Windows\PolicyDefinitions\.

    此时将打开 “目标文件夹访问拒绝 ”对话框，显示“你需要提供管理员权限才能复制到此文件夹”。

11. 单击 “继续 ”按钮。

    将打开 “用户帐户控制 ”对话框。

12. 输入管理员凭据。

选项 1：组策略 (GPO)

这是企业环境中的推荐方法。 组策略可确保跨托管设备进行集中、可审核的管理。

1. 打开 组策略 编辑器 (gpedit.msc) 。

2. 导航到： 计算机配置 > 管理模板 > Microsoft Edge WebView2

3. 查找 配置每应用程序 WebView2 降级版本。

4. 启用策略，并输入以下信息：

   • 名称： 应用程序标识符 (AUMID) 。 或者， .exe 名称，如 ms-teams.exe.

   • 值： 目标四部分版本号 (如 151.0.2178.0) 。

选项 2：注册表编辑器 (regedit)

适用于单台计算机上的目标配置。 需要本地管理员权限。

1. 以管理员身份打开 regedit 。

2. 导航到： HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2

3. 如果) 不存在，请创建名为 (的新 DowngradeVersion 键。

4. 在该键内 DowngradeVersion ，新建一个 String Value (REG_SZ)：

   • 值名称： AUMID 或可执行文件名称 (，例如 ms-teams.exe) 。

   • 值数据： 目标主版本号。

     • 使用四部分数字格式 (（例如 151.0.2178.0) ）将值设置为目标完整版本字符串。

     • IT 管理员可以在稳定渠道的 Microsoft Edge 发行说明中找到确切的由四部分组成的版本号。

     • 示例值：

       • 名称： ms-teams.exe， 值： 151.0.2178.0
       • 名称： olk.exe， 值： 152.0.2164.0

5. 重启 WebView2 应用，使策略生效。

示例：

Key:   HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion
Value: ms-teams.exe = "151.0.2178.0"
Value: olk.exe = "152.0.2164.0"

重要说明

• 仅 HKEY_LOCAL_MACHINE 支持 (HKLM) ; HKEY_CURRENT_USER (HKCU) 将被忽略。

• 不支持以下值：

  • 仅主要值 (，如 151) 。
  • 通配符值 (如 151.*) 。
  • 不是精确的四部分数字版本的值。

• 仅当存在与配置的完整版本完全匹配的文件夹时，WebView2 加载程序才解析运行时安装目录。 例如，151.0.2178.0 必须与 151.0.2178.0 完全匹配。

  如果未找到完全匹配的文件夹，则策略无效，并且运行时默认为策略， BrowserExecutableFolder 或者常青运行时 (默认自动更新运行时) 。

• 如果 Edge 更新程序满足 N-1 和/或 N-2 条件，将 自动下载 所需版本。 IT 管理员无需在磁盘上预暂存版本文件夹。

• 无需重启计算机，但必须重启 WebView2 应用，降级可能需要长达 1 小时才能生效。

• WebView2 应用的策略延迟： 更改将在部署后 1 小时 内生效。 这与 Microsoft Edge 和 WebView2 更新任务节奏一致。 若要触发强制更新，请参阅下面的 触发强制更新。

• 运行时降级策略强制将替代以下内容：

  • 维护窗口。
  • 延长了更新间隔。
  • 缓存的上次检查时间戳。

流程：如何实现降级

1. IT 管理员使用组策略设置策略，指定 AppId 和 TargetVersion。

2. Edge 更新程序读取策略，并验证它在 TargetVersion N-1 或 N-2 范围内。

3. 如果需要，Edge 更新程序将下载 WebView2 运行时的降级版本作为并行安装。

4. Edge 更新程序为目标应用设置 BrowserExecutableFolder 策略，以将其重定向到 WebView2 运行时的指定版本。

5. 只要 WebView2 运行时的降级版本保持在支持的范围内，Edge 更新程序就会维护映射。

6. 当 WebView2 运行时的固定版本超出支持的范围或删除策略时，Edge 更新程序会清理 WebView2 应用并将其还原为使用最新版本的 WebView2 运行时。

如果 WebView2 运行时降级策略处于活动状态，但目标 WebView2 运行时版本尚未下载 (（例如由于网络或磁盘) 约束），则 WebView2 应用将继续使用最新的 WebView2 运行时，直到出现较早的 WebView2 运行时。 WebView2 应用不会仅 因为 WebView2 运行时的降级版本正在等待下载而无法启动。

降级 WebView2 运行时的限制

版本限制

限制	详情
版本范围	仅支持相对于当前常青运行时版本的 WebView2 运行时的版本 N-1 或 N-2。 降级到早于前两个运行时版本的 WebView2 运行时将被拒绝。
版本格式	只有主要版本号 (数字才) 。 完整版本字符串、点或通配符无效。
自动到期	WebView2 运行时的降级版本仅在位于最新的两个前版本中时保持活动状态。 在固定版本之外的两个后续新版本的运行时版本后，降级将自动过期，应用将还原到最新的 WebView2 运行时。
可用性	降级功能仅适用于 Microsoft Edge WebView2 版本 150 或更高版本。

范围限制

限制	详情
仅限企业	在消费者或非托管设备上不受支持。
仅限计算机级别	只能在本地计算机 (HKEY_LOCAL_MACHINE (HKLM) ) 级别设置策略。 不支持为 HKCU) ) (HKEY_CURRENT_USER (当前用户设置降级策略;没有用户级策略或单个用户级控制。
按应用定位	无法跨所有 WebView2 应用执行企业范围的降级。 每个 WebView2 应用都必须单独定位。
没有开发人员控制	只有 IT 管理员才能启动降级 WebView2 运行时。 开发人员无法触发 WebView2 运行时的降级，例如通过 API 进行。
无无限期固定	该解决方案不支持长期或永久版本固定。

共享用户数据文件夹 (UDF) 约束

IT 管理员必须降级共享相同用户数据文件夹 (UDF) 的所有 WebView2 应用，以使用相同的 WebView2 运行时版本。

WebView2 应用可以 (UDF) 共享 WebView2 用户数据文件夹，以重复使用浏览器状态。 很少应用会 (UDF) 共享用户数据文件夹;共享 UDF 的唯一已知应用是 Office 套件应用：Excel、Word 和 PowerPoint。

从不同的 WebView2 运行时版本访问相同的 UDF 是不安全的。 如果 WebView2 应用 A 已降级，并且 WebView2 应用 B 共享相同的 UDF 但未降级，则 WebView2 应用 A 和 WebView2 应用 B 将在启动时快速失败。

降级 WebView2 运行时的风险

安全风险

风险	描述
重新引入的漏洞	降级会重新引入已在较新版本中修复的已修补漏洞。
合规性削弱	在受监管环境中，较旧版本可能违反合规性。
扩大了攻击面	管理多个降级版本会增加过时客户端的持久性。

数据完整性风险

风险	描述
存储损坏	如果存储格式、架构或 API 在 Cookie、IndexedDB、本地存储) (版本之间发生更改，则降级可能会导致损坏或不兼容。
架构不匹配	与使用用户数据快照的 Edge 浏览器不同，WebView2 不实现平台级快照。
用户数据丢失	如果存储格式不兼容，则配置文件不稳定和潜在的数据丢失。

应用兼容性风险

风险	描述
功能依赖关系中断	在降级 WebView2 运行时后，使用较新 WebView2 API 或行为的 WebView2 应用可能会失败或出现不可预知的行为。
性能回归	较旧版本的 WebView2 运行时可能会导致页面加载速度变慢、内存使用率上升和体验降级。
应用故障	由于依赖最近引入的功能或呈现更改，降级 WebView2 运行时可能会导致 WebView2 应用故障。

运营风险

风险	描述
版本碎片	支持在应用级别降级可能导致同一设备上的应用之间的版本偏移。
Sedimentation	随着时间的推移，多个较旧版本会在设备上累积，从而增加复杂性。
磁盘使用量增加	额外的 WebView2 运行时版本与当前常青 WebView2 运行时版本并行安装，这会占用每个设备上的额外磁盘空间。
协调复杂性	降级需要 IT 管理员、WebView2 应用所有者和平台团队之间的认真协调。

对运行时降级进行测试和故障排除

验证是否应用了运行时降级

设置 WebView2 运行时降级策略并重启目标 WebView2 应用后，执行以下操作。

1. 检查版本控制文件夹

1. 在文件资源管理器中，导航到：C:\Program Files (x86)\Microsoft\EdgeWebView\Application\

2. 确认出现与降级版本 (（如) ） 150.0.2178.0 匹配的新文件夹。

   此版本控制文件夹的存在表示 Edge 更新程序已提取并暂存了降级的 WebView2 运行时。

2. 检查注册表策略

1. 确认 DowngradeVersion 已在以下位置设置密钥： HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion

2. 验证条目是否与配置 AppId 的→ TargetVersion匹配。

3. 检查 BrowserExecutableFolder 重定向

• BrowserExecutableFolder应自动设置策略，以将应用指向降级的运行时路径。

触发强制更新

设置 DowngradeVersion 策略后，Edge 更新程序需要下载目标版本。 默认情况下，这在与 Edge/WebView2 更新任务节奏) 保持一致 (大约 1 小时内发生。

若要触发立即更新，请执行以下操作：

1. 以管理员身份打开 PowerShell。

2. 查找 Edge 更新任务：

   Get-ScheduledTask -TaskPath "\Microsoft\EdgeUpdate\*" | Select TaskName, TaskPath

3. 运行任务：

   Start-ScheduledTask -TaskName "<task name from step 2>"

4. 等待几分钟后下载完成。

5. 重启 WebView2 应用。

用于更深入故障排除的诊断工具

以下工具用于 解决问题 — 标准验证不需要它们：

工具	用途
edge://webview2-internals	查看活动的 WebView2 进程，正在使用的运行时版本。
ETW 跟踪	记录更新/降级事件的低级别诊断日志。
事件查看器	检查应用程序日志中是否有 WebView2 更新错误或策略强制执行失败。

常见问题和解决方法

症状	可能的原因	解决方案
仍在最新版本上运行的应用	应用未重启。	重启 WebView2 应用， (不) 计算机。
降级文件夹未显示	版本不在“N-1 或 N-2”范围。	验证目标版本是否在最新的前两个版本中。
应用程序启动时快速失败 (所有应用程序共享用户数据文件夹 (UDF) ) 。	共享 UDF 版本不匹配。	将使用相同 UDF 的所有应用降级到相同版本。
策略未生效。	键路径或值格式不正确。	验证 HKEY_LOCAL_MACHINE (HKLM) 路径、值名称格式 (AUMID 或 .exe) ，以及四部分数字格式 (，如 151.0.2178.0) 。
多个应用意外受到影响。	共享用户数据文件夹	确定 UDF) 共享 (用户数据文件夹，并确保所有受影响的应用一致。
降级意外自动还原。	已固定版本超出支持的范围	在运行时版本不再位于两个早期版本的运行时) 的版本 N-1 或 N-2 (后，WebView2 运行时的降级就会过期，这是预期行为。

删除 WebView2 运行时的降级

选项 1：禁用组策略 (推荐的)

重要提示：请勿直接删除注册表项。 始终使用组策略 (GPO) 来禁用该策略，以确保干净删除并避免孤立配置。

如果使用 GPO 配置降级：

1. 打开 组策略 编辑器 (gpedit.msc) 。

2. 导航到： 计算机配置 > 管理模板 > Microsoft Edge WebView2

3. 将“配置每应用程序 WebView2 降级版本”设置为 “禁用 ”或 “未配置”。

4. 重启 WebView2 应用。

   该应用程序将在下次启动时还原为最新的 Evergreen Runtime。

选项 2：通过注册表删除策略

注意：仅当原始策略是通过注册表编辑器设置时，才应使用直接注册表操作。 如果使用组策略 (GPO) ，请始终使用 GPO 还原以确保一致性。

如果策略最初是直接通过注册表设置的 (则不建议在生产) 中使用：

1. 以管理员身份打开 regedit 。

2. 导航到： HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion

3. 删除特定值 (，如ms-teams.exe) 。

4. 重启 WebView2 应用。

选项 3：自动到期

当固定版本不再位于最新的两个前一个版本中时，降级将自动过期：

• 触发器： 后续两个新的 Evergreen 版本将在固定版本之外发布。

• 行为： Edge 更新程序会自动将适用的应用还原到最新的运行时。

• 需要执行管理员操作：过时策略自动过期后将其删除。

• 示例： 如果在 147 为最新版本 (145 为 N-2) 时降级到版本 145，然后在版本 148 发布时，则版本 145 现在比降级自动到期晚三个版本→。

还原后行为

操作	发生的情况
应用程序重启	WebView2 应用在应用下次启动期间选取最新的 WebView2 运行时。
BrowserExecutableFolder	自动删除;WebView2 应用返回到使用默认 WebView2 运行时路径。
降级的运行时位	由 Edge 更新程序按计划节奏清理。
用户数据	留在原地;不会发生自动数据迁移。

升级和联系 WebView2 团队

呈报路径：

1. 企业管理员联系 Microsoft CSS。

2. CSS 通过本文对此问题进行故障排除。

3. 如果未解决，CSS 会将问题上报给 WebView2 平台团队 ICM。

   区域路径： Edge\Web Experience\WebView2\Distribution

   拥有服务： Edge 浏览器客户事件。

   拥有团队： Edge WebView2。

另请参阅：

• 联系 WebView2 团队

另请参阅

• Microsoft Edge 中的 DowngradeVersion WebView2 - 策略。
• Microsoft Edge Stable 渠道发行说明

外部：

• WebView2 运行时的企业管理
• 联系 WebView2 团队