排查基于事件的加载项和垃圾邮件报告加载项的问题

2025-10-15

开发基于事件的加载项或垃圾邮件报告加载项时，可能会遇到问题，例如加载项未加载或未发生事件。以下部分提供了有关如何对加载项进行故障排除的指导。

查看功能先决条件

验证加载项是否已安装在受支持的客户端上。某些客户端仅支持某些事件或基于事件的激活或集成垃圾邮件报告的各个方面。有关详细信息，请参阅支持的事件和实现集成的垃圾邮件报告加载项。
验证客户端是否支持所需的最低要求集。要求集 1.14 中引入了集成的垃圾邮件报告功能。有关基于事件的激活的内部版本号和要求集的详细信息，请参阅支持的事件。
查看功能的预期行为和限制。

检查清单和 JavaScript 要求

确保在加载项清单中满足以下条件。
- 验证加载项的源文件位置 URL 是否公开可用且防火墙未阻止。此 URL 在仅外接程序清单的 SourceLocation 元素或 "extensions.runtimes.code.page" Microsoft 365 统一清单的属性中指定。
- 验证 <Runtimes> 元素 (仅外接程序清单) 或 "extensions.runtimes.code" 属性 (统一清单) 正确引用包含事件处理程序的 HTML 或 JavaScript 文件。经典 Outlook on Windows 和其他基于 Windows 的 Office 应用程序在运行时使用 JavaScript 文件，而Office web 版、新的 Outlook Mac UI 和新的 Outlook on Windows 使用 HTML 文件。有关如何在清单中配置的示例，请参阅自动设置新邮件或约会的主题的“配置清单”部分。
  
  对于 windows 客户端 (，除了新的 Outlook on Windows) ，必须将所有事件处理 JavaScript 代码捆绑到清单中引用的此 JavaScript 文件中。请注意，大型 JavaScript 捆绑包可能会导致加载项性能出现问题。建议预处理大量作，以便这些作不包含在事件处理代码中。
对于 Windows 客户端 (，除了新的 Outlook on Windows) ，当清单中指定的用于处理事件的 JavaScript 函数运行时，代码在 Office.onReady() 和 Office.initialize 中未运行。建议改为将事件处理程序所需的任何启动逻辑（例如检查用户的客户端版本）添加到事件处理程序。
验证事件处理 JavaScript 文件是否调用 Office.actions.associate。这可确保清单中指定的事件处理程序名称映射到其 JavaScript 对应名称。以下代码是一个示例。
```
Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
```
在版本 2403 (内部版本 17425.20000) 之前的经典 Outlook on Windows 版本中，基于事件的和垃圾邮件报告加载项的 JavaScript 代码仅支持 ECMAScript 2016 和更早的规范。要避免的编程语法的一些示例如下所示。
- 避免在代码中使用 async 和 await 语句。在 JavaScript 代码中包含这些内容将导致加载项超时。
- 避免使用条件 (三元) 运算符，因为这会阻止加载项加载。
如果外接程序只有一个由 Outlook 网页版引用的 JavaScript 文件，在 Windows (新) 和经典) ，在 Mac 上，必须将代码限制为 ECMAScript 2016，以确保外接程序在早期版本的经典 Outlook on Windows 中运行。但是，如果你有一个单独的 JavaScript 文件引用Outlook 网页版、Mac 上的经典 Outlook 的最新版本和新的 Outlook on Windows，则可以在该文件中实现稍后的 ECMAScript 规范。

检查 Webpack 配置

在 Windows 客户端 (，除了新的 Outlook on Windows) ，如果基于事件的外接程序使用 Webpack 捆绑文件，并且事件处理程序永远不会运行，请将外接程序的 Webpack 开发服务器配置为提供静态文件。此方法可防止 Webpack 将代码添加到可能与 JavaScript 运行时不兼容的外接程序文件。将外接程序配置为使用静态文件，如下所示：

在 webpack.config.js 加载项的文件中，导入 Node.js path 模块。
```
const path = require("path");
```

在同一文件中，将 Webpack 开发服务器配置为提供文件夹中的 dist 静态文件。

...
devServer: {
  static: {
    directory: path.join(__dirname, "dist"),
    publicPath: "/public",
  },
  ...
}
...

运行 npm run build。
在加载项清单中，更新事件处理 JavaScript 文件的路径，以引用从静态目录提供的生成文件。例如，https://localhost:3000/public/launchevent.js。

调试加载项

对加载项进行更改时，请注意：
- 如果更新清单，请删除加载项，然后再次旁加载它。有关如何从 Outlook 中删除旁加载加载项的信息，请参阅旁加载用于测试的 Outlook 加载项。如果使用的是 Outlook on Windows，则还必须关闭并重新打开 Outlook。
- 如果对清单以外的文件进行更改，请在 Windows 或 Mac 上关闭并重新打开 Office 客户端，或刷新运行Office web 版的浏览器选项卡。
- 如果在执行这些步骤后仍无法看到更改，请清除 Office 缓存。
在 Windows 上的 Office 中测试加载项时， (不包括新的 Windows 版 Outlook) ：
- 对于基于事件的外接程序，检查任何报告的加载项错误事件查看器。
  1. 在“事件查看器”中，选择“Windows 日志>应用程序”。
  2. 在 “作” 面板中，选择“ 筛选当前日志”。
  3. 从“ 记录” 下拉列表中，选择首选的日志时间范围。
  4. 选中 “错误 ”复选框。
  5. 在 “事件 ID” 字段中，输入 63。
  6. 选择 “确定” 以应用筛选器。
- 验证 bundle.js 文件是否已下载到文件资源管理器中的以下文件夹。中 [] 括起来的文本表示适用的 Office 和外接程序信息。
```
%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\{[Office profile GUID]}\[Office account encoding]\Javascript\[Add-in ID]_[Add-in Version]_[locale]
```
  提示
  - 为便于阅读，本文将文件名称为 bundle.js，但确切名称取决于 Office 应用程序。
    - Excel： bundle_excel.js
    - Outlook： bundle.js。
    - PowerPoint： bundle_powerpoint.js
    - Word： bundle_word.js
  - 没有直接方法可以确定 bundle.js 文件路径中使用的 Office 配置文件 GUID 和帐户编码。查找外接程序 bundle.js 文件的最有效方法是手动检查每个文件夹，直到找到包含外接程序 ID 的 Javascript 文件夹。
  - 首次安装加载项时， bundle.js 文件将下载到本地 Wef 文件夹。每次启动或重启 Office 应用程序时，都会刷新它。如果 bundle.js 文件未显示在 Wef 文件夹中，并且加载项已安装或旁加载，请重启 Office。对于 Outlook，可能需要删除加载项，然后再次旁加载。
在桌面客户端上测试加载项 (排除新的 Outlook on Windows) 启用运行时日志记录以识别可能的清单和加载项安装问题。有关如何使用运行时日志记录的指南，请参阅使用运行时日志记录调试加载项。
在代码中设置断点以调试加载项。有关特定于平台的说明，请参阅调试基于事件的加载项和垃圾邮件报告加载项。

寻求其他帮助

如果在执行建议的故障排除步骤后仍需要帮助，请打开 GitHub 问题。包括屏幕截图、视频录制或运行时日志，以补充报表。

另请参阅

反馈

此页面是否有帮助？