迁移至Azure后Excel (Office.js)加载项无法加载（已适配清单）

云原生阿岚

2026-6-16

Excel加载项部署Azure后无法加载的排查方案

问题概述

使用Yeoman生成器基于Office.js开发的Excel加载项，本地侧载（npm start）正常，但替换清单URL为Azure静态应用地址后无法加载。浏览器可正常访问所有URL，排除证书问题（证书错误有专属提示）。Excel提示网络连接问题，但网络正常，功能区图标也加载失败；尝试网络共享、Office 365管理中心部署均无效，部分场景下微软验证器显示清单有效，但Excel仍提示“清单无效”。需要获取加载失败的具体日志。

清单文件

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <Id>916751c4-49dd-445f-b668-6ea66c72ce15</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="_Wechselkursdifferenzbesteuerung"/>
  <Description DefaultValue="Plugin um die Wechselkursdifferenzberechnung zu automatisieren."/>
  <IconUrl DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/assets/icon-32.png"/>
  <HighResolutionIconUrl DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/assets/icon-64.png"/>
  <SupportUrl DefaultValue="https://www.contoso.com/help"/>
  <AppDomains>
    <AppDomain>https://kind-moss-07d7a0503.5.azurestaticapps.net</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Workbook"/>
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="CustomFunctionsRuntime" MinVersion="1.1"/>
    </Sets>
  </Requirements>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/taskpane.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <AllFormFactors>
          <ExtensionPoint xsi:type="CustomFunctions">
            <Script>
              <SourceLocation resid="Functions.Script.Url"/>
            </Script>
            <Page>
              <SourceLocation resid="Functions.Page.Url"/>
            </Page>
            <Metadata>
              <SourceLocation resid="Functions.Metadata.Url"/>
            </Metadata>
            <Namespace resid="Functions.Namespace"/>
          </ExtensionPoint>
        </AllFormFactors>
        <DesktopFormFactor>
          <GetStarted>
            <Title resid="GetStarted.Title"/>
            <Description resid="GetStarted.Description"/>
            <LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
          </GetStarted>
          <FunctionFile resid="Commands.Url"/>
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <OfficeTab id="TabHome">
              <Group id="CommandsGroup">
                <Label resid="CommandsGroup.Label"/>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Control xsi:type="Button" id="TaskpaneButton">
                  <Label resid="TaskpaneButton.Label"/>
                  <Supertip>
                    <Title resid="TaskpaneButton.Label"/>
                    <Description resid="TaskpaneButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>ButtonId1</TaskpaneId>
                    <SourceLocation resid="Taskpane.Url"/>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/assets/icon-64.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/assets/icon-64.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/assets/icon-64.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/commands.html"/>
        <bt:Url id="Taskpane.Url" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/taskpane.html"/>
        <bt:Url id="GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="Functions.Namespace" DefaultValue="CONTOSO"/>
        <bt:String id="CommandsGroup.Label" DefaultValue="Commands Group"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="Plugin Starten"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="GetStarted.Title" DefaultValue=" Wechselkursdifferenzbesteuerungsplugin"/>
        <bt:String id="GetStarted.Description" DefaultValue="Einfach auf den Plugin Starten Knopf klicken und dem Handbuch folgen"/>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue=" Wechselkursdifferenzbesteuerungsplugin starten"/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

核心问题修复

1. 清单资源缺失

清单中CustomFunctions扩展点引用了Functions.Script.Url、Functions.Page.Url、Functions.Metadata.Url三个资源ID，但<bt:Urls>里未定义这些URL，导致Excel找不到自定义函数相关资源，直接加载失败。

修复：在<bt:Urls>节点下添加以下内容（路径需匹配Azure实际部署位置，Yeoman生成的项目通常在dist目录）：

<bt:Url id="Functions.Script.Url" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/dist/custom-functions.js"/>
<bt:Url id="Functions.Page.Url" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/taskpane.html"/>
<bt:Url id="Functions.Metadata.Url" DefaultValue="https://kind-moss-07d7a0503.5.azurestaticapps.net/dist/custom-functions.json"/>

2. 图标尺寸不匹配

功能区图标Icon.16x16、Icon.32x32都指向64px的图标文件，Excel对图标尺寸有严格要求，尺寸不符会导致图标加载失败，进而影响整个加载流程。

修复：替换为对应尺寸的图标文件，确保：

Icon.16x16指向16px的图标
Icon.32x32指向32px的图标
Icon.80x80建议使用80px图标（也可兼容64px，但优先匹配尺寸）

加载失败日志获取

Windows端Excel

打开注册表编辑器（regedit），导航至HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Wef\Developer
创建DWORD值EnableLogging，设置为1
重启Excel并尝试加载加载项
日志位于%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\Logs目录

Mac端Excel

终端执行命令：defaults write com.microsoft.Excel OfficeAddinDeveloperExtras -bool true
重启Excel，加载加载项
打开“开发工具”选项卡，点击“加载项调试工具”查看日志

部署补充排查

网络共享部署：确认共享文件夹权限正确，Excel可读取清单，且所有URL可被客户端访问
Office 365管理中心部署：检查部署状态，清除Office缓存：
- Windows：删除%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\下所有文件
- Mac：删除~/Library/Containers/com.microsoft.Excel/Data/Library/Application Support/Microsoft/Office/16.0/Wef/下所有文件
Azure CORS设置：在Azure门户静态应用的CORS设置中，添加https://*.officeapps.live.com、https://*.office.com等允许的来源
HTML文件检查：确保taskpane.html、commands.html中无localhost脚本引用，全部替换为Azure地址

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

迁移至Azure后Excel (Office.js)加载项无法加载（已适配清单）

问题概述 #

清单文件 #

核心问题修复 #

1. 清单资源缺失 #

2. 图标尺寸不匹配 #

加载失败日志获取 #

Windows端Excel #

Mac端Excel #

部署补充排查 #