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

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

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

選擇插件開發工作流程

方法	最適合	權衡
`.plugin`在外掛程式管理器中安裝歸檔文件	首次安裝、快速測試或偶爾更改	簡單易用且受支持，但每次原始程式碼更改後都必須重新建置和重新安裝存檔。
將已安裝的插件資料夾連結到您的來源資料夾	開發過程中頻繁修改	刪除重複打包，但需要正確的使用者路徑，並且需要重新載入或重新開啟才能使變更生效。
使用調試標誌啟動	檢查控制台輸出、插件幀或斷點	啟用開發者工具；不會安裝外掛程式或自動載入不受信任的程式碼。

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

準備插件文件

首先，建立一個本機插件目錄，其中至少包含插件所需的文件，包括 `<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。

首次安裝插件

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

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

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

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

作業系統	使用者插件目錄
視窗	`%LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\`
macOS	`~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/`
Linux	`~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/`

在目錄內部，連結名稱是花括號內的 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` 可還原預設狀態。持久化的開發者工具在專用測試機上很方便，但在共用工作站上啟用它們會增加系統混亂，並在您不需要時仍保留這些檢查工具。