Azure DevOps扩展首次加载失败：相对路径解析异常

问题概述 #

这是一款集成于Azure DevOps待办页面的ms.vss-work-web.backlog-panel类型面板扩展，通过待办页面右上角「视图选项」按钮打开。首次打开待办页面并加载扩展面板时，会弹出“发布者的扩展加载失败”错误；刷新页面后功能恢复正常。该问题每日或间隔数小时出现一次，浏览器隐身窗口中可轻松复现。

路径解析异常详情 #

首次加载时，面板iframe配置的相对路径"dist/assistant-toolpane/assistant-toolpane.html"被错误解析为待办页面的相对路径：

https://dev.azure.com/{Organization}/{Project}/_backlogs/backlog/{Team}/dist/assistant-toolpane/assistant-toolpane.html

刷新后则正确解析到Azure Marketplace的CDN地址：

https://{publisher}.gallerycdn.vsassets.io/extensions/{publisher}/{extension-name}/0.0.205/1747466899824/dist/assistant-toolpane/assistant-toolpane.html

已尝试的无效方案 #

• 在URI前添加~符号，导致路径被解析为无效地址，刷新后也无法正常加载
• 尝试使用contentUri属性，但该属性不适用于ms.vss-work-web.backlog-panel类型
• 硬编码绝对URL，因CDN资产令牌无法预知而不可行

可行解决方案 #

方案1：使用Manifest占位符配置URI #

在扩展的vss-extension.json配置文件中，使用Azure DevOps扩展内置的{{extensionUri}}占位符替代纯相对路径，该占位符会自动替换为扩展的CDN基础地址：

"contributions": [
  {
    "id": "your-backlog-panel-id",
    "type": "ms.vss-work-web.backlog-panel",
    "targets": ["ms.vss-work-web.backlog-view"],
    "properties": {
      "name": "Assistant Toolpane",
      "uri": "{{extensionUri}}/dist/assistant-toolpane/assistant-toolpane.html"
    }
  }
]

方案2：通过VSS SDK动态获取路径 #

如果面板iframe是通过代码动态创建的，可使用VSS SDK提供的扩展上下文获取正确的基础路径，拼接成完整资源URL：

VSS.init({ explicitNotifyLoaded: true });
VSS.ready().then(() => {
  const extensionContext = VSS.getExtensionContext();
  const fullToolPaneUrl = `${extensionContext.extensionUri}/dist/assistant-toolpane/assistant-toolpane.html`;
  // 将fullToolPaneUrl设置为iframe的src属性
});

两种方案均无需自行托管扩展资源，完全依赖Azure Marketplace默认托管即可解决路径解析异常问题。

内容的提问来源于stack exchange，提问作者Jon Koeter