排查 Office 加载项中的开发错误

项目
11/19/2024

下面是开发 Office 外接程序时可能遇到的常见问题的列表。

提示

清除 Office 缓存通常会修复与过时代码相关的问题。这可确保使用当前文件名、菜单文本和其他命令元素上传最新的清单。若要了解详细信息，请参阅清除 Office 缓存。

外接程序无法在任务窗格中加载，或外接程序清单存在其他问题

请参阅验证 Office 加载项的清单和使用运行时日志记录功能调试加载项，以调试加载项清单问题。

功能区自定义项未按预期呈现

旁加载并运行加载项后，将加载项功能区图标的 URL 粘贴到浏览器的导航栏中，并查看图标文件是否打开。
默认情况下，将禁止显示连接到 Office UI 的加载项错误。可以通过以下步骤打开这些错误消息。
1. 删除加载项后，打开 Office 应用程序的“ 文件 ”选项卡。
2. 选择“选项”。
3. 在 “选项 ”对话框中，选择“ 高级”。
4. 在 Outlook) 的“ 常规 ”部分 (“ 开发人员 ”部分，启用 “显示加载项用户界面错误”。
再次旁加载加载项，并查看是否存在任何错误。

清除缓存有助于确保使用外接程序清单的最新版本。若要清除 Office 缓存，请按照清除 Office 缓存中的说明进行操作。如果使用Office web 版，请通过浏览器的 UI 清除浏览器缓存。

旧开发外接程序中的外接程序命令即使在清除缓存后仍保留在功能区上

有时，当你运行 Office 应用程序时，你过去正在开发的加载项中的按钮或菜单会显示在功能区上，即使在清除缓存后也是如此。请尝试以下方法：

如果在多台计算机上开发加载项，并且用户设置跨计算机同步，请尝试清除所有计算机上的 Office 缓存。关闭所有计算机上的所有 Office 应用程序，然后在打开其中任何一台计算机上的任何 Office 应用程序之前清除所有这些计算机上的缓存。
如果将旧加载项的清单发布到网络共享，请关闭所有 Office 应用程序，清除缓存， 并确保从共享文件夹中删除加载项的清单。

对静态文件（例如 JavaScript、HTML 和 CSS）的更改未生效

浏览器可能正在缓存这些文件。若要阻止此操作，请在开发时关闭客户端缓存。详细信息取决于你所使用的服务器类型。在大多数情况下，它涉及将某些标头添加到 HTTP 响应。建议使用以下集。

Cache-Control：“private、no-cache、no-store”
Pragma：“no-cache”
过期：“-1”

有关在 Node.JS Express 服务器中执行此操作的示例，请参阅此 app.js 文件。有关 ASP.NET 项目中的示例，请参阅此 cshtml 文件。

如果加载项托管在 Internet Information Server (IIS) 中，则还可以将以下内容添加到 web.config 中。

<system.webServer>
  <staticContent>
    <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="0.00:00:00" cacheControlCustom="must-revalidate" />
  </staticContent>

如果这些步骤一开始似乎不起作用，则可能需要清除浏览器的缓存。请通过浏览器的 UI 执行此操作。有时，当你尝试在边缘 UI 中清除边缘缓存时，无法成功清除它。如果出现这种情况，请在 Windows 命令提示符中运行以下命令。

del /s /f /q %LOCALAPPDATA%\Packages\Microsoft.Win32WebViewHost_cw5n1h2txyewy\AC\#!123\INetCache\

不会对属性值进行更改，并且没有错误消息

查看属性的参考文档，了解它是否为只读。此外，Office JS 的 TypeScript 定义指定哪些对象属性是只读的。如果尝试设置只读属性，写入操作将以无提示方式失败，并且不会引发错误。以下示例错误地尝试设置只读属性 Chart.id。另请参阅某些属性无法直接设置。

// This will do nothing, since `id` is a read-only property.
myChart.id = "5";

出现错误：“此加载项不再可用”

下面是导致此错误的一些原因。如果发现其他原因，请使用页面底部的反馈工具告诉我们。

如果使用 Visual Studio，则旁加载可能存在问题。关闭 Office 主机和 Visual Studio 的所有实例。重启 Visual Studio 并再次尝试按 F5。
加载项清单已从其部署位置（例如集中部署、SharePoint 目录或网络共享）中删除。
清单中 ID 元素的值已直接在已部署的副本中更改。如果出于任何原因想要更改此 ID，请先从 Office 主机中删除加载项，然后将原始清单替换为已更改的清单。许多人需要清除 Office 缓存以删除原始的所有跟踪。有关清除操作系统缓存的说明，请参阅清除 Office 缓存一文。
加载项清单的清单中resid未在清单的“资源”部分的任意位置定义，或者，在使用它的位置与在 Resources> 节中<定义的位置之间的拼写resid不匹配。
resid清单中的某个属性超过 32 个字符。属性resid和 idResources> 节中<相应资源的属性不能超过 32 个字符。
加载项具有自定义外接程序命令，但你尝试在不支持加载项的平台上运行它。有关详细信息，请参阅外接程序命令要求集。

加载项在 Edge 上不起作用，但适用于其他浏览器

请参阅排查 EdgeHTML 和 WebView2 (Microsoft Edge) 问题。

Excel 加载项引发错误，但不一致

有关可能的原因，请参阅 Excel 加载项疑难解答。

Word加载项引发错误或显示损坏行为

有关可能的原因，请参阅排查Word加载项问题。

Visual Studio 项目中的清单架构验证错误

如果使用需要更改清单文件的较新功能，则可能在 Visual Studio 中收到验证错误。例如，添加 <Runtimes> 元素以实现共享运行时时，可能会看到以下验证错误。

命名空间“”中的元素“Host”http://schemas.microsoft.com/office/taskpaneappversionoverrides在命名空间“”中具有无效的子元素“Runtimes”http://schemas.microsoft.com/office/taskpaneappversionoverrides

如果发生这种情况，可以将 Visual Studio 使用的 XSD 文件更新到最新版本。最新架构版本位于 [MS-OWEMXML]：附录 A：完整 XML 架构。

找到 XSD 文件

在 Visual Studio 中打开项目。
在 解决方案资源管理器 中，打开 manifest.xml 文件。清单通常位于解决方案下的第一个项目中。
(F4) 选择“ 查看>属性窗口 ”。
设置 manifest.xml 中的光标选择，以便 “属性” 窗口显示 XML 文档 属性。
在 “属性” 窗口中，选择“ 架构” 属性，然后选择省略号 (...) 打开 XML 架构 编辑器。可在此处找到项目使用的所有架构文件的确切文件夹位置。

属性窗口显示 XML 文档属性。

更新 XSD 文件

在文本编辑器中打开要更新的 XSD 文件。验证错误中的架构名称将与 XSD 文件名相关联。例如，打开 TaskPaneAppVersionOverridesV1_0.xsd。
在 [MS-OWEMXML]：附录 A：完整 XML 架构中找到更新的架构。例如，TaskPaneAppVersionOverridesV1_0位于 taskpaneappversionoverrides 架构中。
将文本复制到文本编辑器中。
保存更新的 XSD 文件。
重启 Visual Studio 以选取新的 XSD 文件更改。

对于已过期的任何其他架构，可以重复上述过程。

脱机工作时，没有 Office API 工作

从本地副本而不是 CDN 加载 Office JavaScript 库时，如果库不是最新的，API 可能会停止工作。如果已离开项目一段时间，请重新安装库以获取最新版本。该过程因 IDE 而异。根据环境选择以下选项之一。

Visual Studio：按照以下步骤更新 NuGet 包。
1. 选择 “工具>”“NuGet 包管理器>”“管理解决方案的 Nuget 包”。
2. 选择“更新”选项卡。
3. 选择“Microsoft.Office.js”。确保包源来自 nuget.org。
4. 在左窗格中，选择“ 安装 ”并完成包更新过程。
任何其他 IDE：获取最新的 npm 包 @microsoft/office-js 和 @types/office-js。

通过