通过

非共享运行时中的自定义函数调试

  • 项目

本文讨论仅针对不使用共享运行时的自定义函数进行调试。 若要调试使用共享运行时的自定义函数加载项，请参阅 调试 Office 外接程序概述。

重要

请注意，以下平台上可以使用 Excel 自定义函数。

  • Office 网页版
  • Windows 版 Office
    • Microsoft 365 订阅
    • 零售永久 Office 2016 及更高版本
    • 批量许可永久Office 2021及更高版本
  • Mac 版 Office

以下各项当前不支持 Excel 自定义函数：

  • iPad 版 Office
  • Windows 上 Office 2019 或更早版本的批量许可永久版本

注意

建议对 共享运行时使用自定义函数，除非有特定原因不使用共享运行时。 请注意，使用共享运行时意味着，如果满足条件，外接程序将使用基于 WebView2 (Microsoft Edge Chromium 的) ;否则，外接程序将使用 Trident (Internet Explorer 11) 无论 Windows 或 Microsoft 365 版本如何。 有关 WebView2 条件的说明，请参阅 Office 外接程序使用的浏览器和 Webview 控件。有关运行时的详细信息，请参阅 Office 外接程序中的运行时。

提示

本文中所述的调试技术不适用于使用 Office 外接程序项目创建的项目，这些项目包含 Yeoman 生成器中的 “仅清单 ”选项。 本文稍后引用的脚本未随该选项一起安装。 若要调试使用此选项创建的加载项，请根据需要参阅以下文章之一中的说明。

为不使用共享运行时的加载项调试自定义函数的过程因目标平台 (Windows、Mac 或 Web) 以及使用的是Visual Studio Code还是其他 IDE 而异。 使用下表中的链接访问本文中与调试方案相关的部分。 在此表中，“CF-NSR”是指非共享运行时中的自定义函数。

目标平台 Visual Studio Code 其他 IDE
Excel 网页版 使用 VS Code 和浏览器开发工具 使用命令行工具
Windows 版 Excel 使用 VS Code 和浏览器开发工具 不支持在 Vs Code 外部的 Windows 上的 Excel 中调试 CF-NSR。 针对Excel web 版进行调试。
Mac 版 Excel 不支持在 Excel on Mac 中运行的 CF-NSR 的 VS Code 调试。 针对Excel web 版进行调试。 使用命令行工具

使用浏览器开发人员工具调试 Excel web 版 中的自定义函数

可以使用浏览器开发人员工具来调试不使用Excel web 版共享运行时的自定义函数。 以下步骤适用于 Windows 和 macOS。

从 Visual Studio Code 运行加载项

  1. 在 Visual Studio Code (VS Code) 中打开自定义函数根项目文件夹。
  2. 选择 “终端>运行任务” 并键入或选择“ 监视”。 这将监视和重新生成任何文件更改。
  3. 选择 “终端>运行任务” ，然后键入或选择“ 开发服务器”。

旁加载加载项

  1. 打开Office web 版。

  2. 打开新的 Excel 工作簿。

  3. 选择“ 主页>加载项”，然后选择“ 更多设置”。

  4. 在 “Office 加载项 ”对话框中，选择“ 上传我的外接程序”。

  5. 转到加载项清单文件，再选择“上传”。

    带浏览、上载和取消按钮的上载外接程序对话框。

注意

旁加载到文档后，每次打开文档时，它都将保持旁加载状态。

开始调试

  1. 在浏览器中打开开发人员工具。 对于 Chrome 和大多数浏览器，F12 将打开开发人员工具。
  2. 在开发人员工具中，使用 Cmd+P 或 Ctrl+P (functions.js 或 functions.ts) 打开源代码脚本文件。
  3. 在自定义函数源代码中设置断点。

如果需要更改代码，可以在 VS Code 中编辑并保存更改。 刷新浏览器以查看已加载的更改。

使用命令行工具进行调试

如果不使用 VS Code，可以使用命令行 (（如 bash 或 PowerShell) ）来运行加载项。 需要使用浏览器开发人员工具来调试 Excel web 版 中的代码。 不能使用命令行调试 Excel 的桌面版本。

  1. 从命令行运行 npm run watch 到 watch，并在代码发生更改时重新生成。

  2. 打开第二个命令行窗口 (运行 watch.)

  3. 如果要在桌面版本的 Excel 中启动加载项，并且项目package.json文件的“脚本”部分具有“start：desktop”脚本，请运行 npm run start:desktop;否则运行 npm run start。

    或者，如果想要在 Excel web 版启动加载项，请运行以下命令。

    npm run start -- web --document {url} (，其中 {url} 是 OneDrive 或 SharePoint) 上的 Excel 文件的 URL

    注意

    如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

    如果加载项未在文档中旁加载，请按照 旁加载加载项 中的步骤旁加载加载项。 然后继续下一部分开始调试。

  4. 在浏览器中打开开发人员工具。 对于 Chrome 和大多数浏览器，F12 将打开开发人员工具。

  5. 在开发人员工具中，打开源代码脚本文件 (functions.js 或 functions.ts) 。 自定义函数代码可能位于文件末尾附近。

  6. 在自定义函数源代码中，通过选择一行代码来应用断点。

如果需要更改代码，可以在 VS Code 中编辑并保存更改。 刷新浏览器以查看已加载的更改。

用于生成和运行加载项的命令

有几个生成任务可用。

  • npm run watch：为开发生成，并在保存源文件时自动重新生成
  • npm run build-dev：为开发生成一次
  • npm run build：生产版本
  • npm run dev-server：运行用于开发的 Web 服务器

可以使用以下任务在桌面或联机上开始调试。

  • npm run start:desktop：在桌面上启动 Excel 并旁加载加载项。 如果项目package.json文件的“scripts”部分中不存在“start：desktop”脚本，请改为运行 npm run start 。

  • npm run start -- web --document {url} (，其中 {url} 是 OneDrive 或 SharePoint) 上的 Excel 文件的 URL：启动Excel web 版并旁加载加载项。

    注意

    如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

  • npm run stop：停止 Excel 和调试。

后续步骤

了解 在没有共享运行时的情况下对自定义函数进行身份验证。

另请参阅