如何在 ONLYOFFICE 桌面編輯器中啟用插件開發

ONLYOFFICE 桌面編輯器沒有提供任何「啟用外掛程式開發」的文件。支援的工作流程是透過插件管理器安裝您自己的插件，將其放置在本機插件資料夾中，並可選擇將已安裝的插件副本替換為指向您的工作原始程式碼資料夾的符號連結。若要檢查錯誤和使用斷點，請使用文件中提供的偵錯標誌啟動桌面應用程式。這些是兩個獨立的步驟：調試模式會啟用開發者工具，而安裝或連結外掛程式則會使其可供編輯器使用。

目前的 ONLYOFFICE API 文件描述了相同的桌面工作流程，並記錄了一個用於在啟動時保持調試模式啟用的標誌。我沒有找到任何關於更改這些步驟的新開發模式開關的官方通知。本指南遵循 2026 年 10 月 6 日發布的官方說明。路徑可能因安裝類型而異，因此在變更檔案之前，請確認適用於您平台的路徑。

選擇插件開發工作流程

對於大多數開發者來說，只需使用一次插件歸檔檔案來註冊插件，然後使用符號連結進行後續迭代即可。僅在診斷代碼時才添加調試標誌。除非每次啟動都需要開發者工具，否則請保持其持久化版本關閉。

準備插件文件

首先，建立一個本機插件目錄，其中至少包含插件所需的文件，包括 `<plugin_name>`config.json和 `<plugin_name> index.html`。設定檔必須包含有效的外掛程式 GUID，並使用 ONLYOFFICE 外掛程式架構指向外掛程式的入口頁面和資源。完整的架構請參考官方範例外掛程式或 API 文件；格式錯誤的 GUID、錯誤的路徑或無效的配置都可能導致插件無法顯示。

GUIDconfig.json通常採用 `<plugin_name>.<plugin_name>` 的形式asc.{YOUR-GUID}。桌面編輯器使用 GUID 作為插件資料夾名稱，但省略asc.前綴。請確保來源目錄、壓縮套件和安裝路徑中的 GUID 相同。請勿重複使用內建外掛程式或其他已安裝插件的 GUID。

首次安裝插件

1. 將插件的檔案和子資料夾放入一個 ZIP 壓縮包中。檔案本身必須位於壓縮包根目錄，而不能放在額外的專案資料夾中。
2. 將存檔擴展名從 . 更改.zip為.plugin.
3. 開啟 ONLYOFFICE 桌面編輯器，選擇「外掛程式」選項卡，然後按一下「外掛程式管理器」。
4. 開啟「我的插件」，選擇「手動安裝插件」，選擇.plugin文件，然後確認。

插件隨後會出現在目前開啟的編輯器以及之後開啟的編輯器的「插件」標籤中。手動歸檔方式無需網路連線即可運作。應用程式市場安裝適用於即用型插件；它不能取代您自行建置的開發版本。

使用符號連結可以加快迭代速度

首次安裝後，桌面編輯器會在某個sdkjs-plugins目錄中儲存一份副本。請將該副本替換為指向來源資料夾的符號鏈接，以便您可以直接編輯工作文件。在更改已安裝的測試外掛程式資料夾之前，請關閉桌面編輯器。請備份來源資料夾或確保其完整無損，並僅刪除與您的測試插件 GUID 相符的資料夾。

在目錄內部，連結名稱是花括號內的 GUID，不含asc.前綴。例如，如果配置 GUID 為 `<configuration GUID>` asc.{91EAC419-EF8B-440C-A960-B451C7DF3A37}，則資料夾或連結名稱為 `<folder 或 link 名稱> {91EAC419-EF8B-440C-A960-B451C7DF3A37}`。

視窗

如果您的 Windows 帳戶或政策要求，請以管理員身分開啟命令提示字元。關閉編輯器並將已安裝的測試插件資料夾移開後，建立目錄連結：

mklink /D "%LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\{YOUR-GUID}" "C:\path\to\your\plugin"

請將兩個佔位符分別替換為來源目錄的 GUID 和完整路徑。連結目標必須不存在。

macOS

ln -s "/path/to/your/plugin" "$HOME/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/{YOUR-GUID}"

Linux

ln -s "/path/to/your/plugin" "$HOME/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/{YOUR-GUID}"

請使用已安裝版本的路徑；打包版本或沙盒版本可能會將使用者資料儲存在其他位置。編輯原始碼後，請根據需要重新開啟文件或重新載入插件。符號連結可以避免重新建立歸檔文件，但更改不一定會在編輯器重新載入插件後立即生效。

使用開發者工具啟動桌面編輯器

要調試插件，請完全退出桌面編輯器，然後使用相應的命令啟動它--ascdesktop-support-debug-info。請使用適用於您作業系統的命令；如果您將應用程式安裝在自訂位置，請調整可執行檔案路徑。

視窗

在命令提示字元中執行以下命令：

"%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info

或者，您也可以編輯捷徑的「目標」字段，在可執行檔案路徑後新增一個空格和對應的標誌。這將影響透過該捷徑啟動的檔案。

Linux

"/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info

macOS

"/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

套用運行後，點擊文件內部並按下快捷鍵F1，或右鍵點擊可編輯的工具列欄位並選擇「檢查元素」。在開發者工具中，選擇插件的 iframe 以檢查其自身的 JavaScript 程式碼和日誌。傳遞給 `<script>` 標籤的程式碼callCommand在名為 `<script>` 的編輯器框架中運行frameEditor，因此其錯誤和斷點可能出現在與插件 UI 程式碼不同的上下文中。

可選標誌--ascdesktop-support-debug-info-keep=1可使偵錯模式在每次啟動時保持啟用狀態。若要關閉持久狀態，請使用 `--debug-mode` 啟動--ascdesktop-support-debug-info-keep=0；使用 ` --ascdesktop-support-debug-info-keep=default--default-debug-mode` 可還原預設狀態。持久化的開發者工具在專用測試機上很方便，但在共用工作站上啟用它們會增加系統混亂，並在您不需要時仍保留這些檢查工具。

檢查開發環境是否正常運作

• 插件會以其配置的名稱顯示在「插件」標籤中。
• 原始碼變更後，重新開啟文件或重新載入外掛程式即可顯示更新後的行為。
• 使用調試標誌啟動後，可以F1透過「檢查元素」開啟開發者工具。
• 選取插件 iframe 時，會顯示插件 UI 程式碼的日誌；文檔指令在frameEditor.

如果外掛程式缺失，請確認其config.json位於index.html歸檔根目錄，GUID 有效，且資料夾使用的 GUID 不含asc.前綴。確認連結指向來源目錄，而不是包含來源目錄的父目錄。如果插件出現但表現得像舊版本，請關閉並重新開啟文檔，以便編輯器重新載入連結的文件。

此設定無法實現的功能

桌面調試標誌並非插件開發的全域權限開關。安裝插件包或將資料夾放置在支援的插件目錄中即可使該插件可用；調試標誌僅用於啟用檢查工具。同樣，透過 URL 將外掛程式載入到 Web 編輯器中的說明並不自動適用於桌面編輯器。請使用上述針對桌面平台的安裝和調試流程。

這些指南適用於 ONLYOFFICE 桌面編輯器外掛程式。它們並未說明如何在 DocSpace 中啟用插件、如何在 ONLYOFFICE Docs 中設定伺服器端插件，或如何將插件發佈到 Marketplace。對於這些工作流程，請參閱相應的官方產品文件。

官方參考資料

• ONLYOFFICE：開發插件
• ONLYOFFICE：為桌面編輯器開發插件
• ONLYOFFICE：在桌面編輯器中安裝和測試插件
• ONLYOFFICE：以調試模式運行桌面編輯器
• ONLYOFFICE：桌面編輯器中的插件調試
• ONLYOFFICE：官方外掛程式範例和原始碼庫