Skip to main content

本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。

远程调试是迭代插件最快的方式。插件进程在你的笔记本上运行，而 Dify 会把它当作已安装在工作空间中的插件。保存修改并重启进程，改动即刻生效。

前置条件#

  • 能在 Dify 工作空间的 集成 中打开 调试。调试 只对 谁可以调试？ 设置所允许的成员显示，这项设置由工作空间所有者和管理员控制。
  • 一个已搭建好的插件项目（若尚未创建，参见 CLI）。
  • 已安装 Python 3.12 及插件的依赖（pip install -r requirements.txt）。

步骤 1：获取调试 URL 和 Key#

在 集成 中，点击侧边栏底部的 调试，然后复制 Port 和 Key 两个值。

地址类似 debug-plugin.dify.dev:5003。该 Key 为你的工作空间独有，任何持有它的人都能挂载插件，因此不要外泄。

步骤 2：配置插件的 .env#

在插件项目中，将 .env.example 复制为 .env 并填入对应值：

Note

REMOTE_INSTALL_URL 是步骤 1 中合并后的 host:port，而非两个独立的变量。

步骤 3：运行插件#

在插件项目目录下：

进程会保持在前台运行，并记录传入的调用。修改代码后重启进程即可应用改动。

步骤 4：验证安装#

回到 集成，在插件类型对应的分区里找到它。比如你开发的是工具，它就会和其他工具插件列在一起。

Check

插件磁贴会显示调试标识，本地终端会记录首次注册握手。挂载成功。

工作空间的其他成员也能看到并使用它，前提是你的本地进程保持连接。

像调用其他插件一样触发它：从工作流节点调用、在 Agent 中作为工具运行，或访问端点 URL。调用会落到你的本地进程上，你可以接入调试器。

故障排查#

连接被拒绝 / 无法访问地址

守护进程没有在 REMOTE_INSTALL_URL 填写的地址上监听。在自部署环境中，确认守护进程容器已设置 PLUGIN_REMOTE_INSTALLING_ENABLED=true 且 5003 端口已暴露。在云端，请再次核对所复制的 host:port 是否与 调试 中显示的完全一致。

插件已启动但始终不出现在插件列表中

最常见的原因是 REMOTE_INSTALL_KEY 失效或填错。从 调试 中复制当前的 Key 填入 .env，再运行一次 python -m main。同时确认守护进程日志显示了传入的注册请求。

`plugin_unique_identifier is not valid`

manifest.yaml 或 provider/*.yaml 中的 author 字段不是守护进程接受的值。将其设为你的 GitHub 用户名，然后重启。

改动不生效

每次修改后插件进程都需要重启，没有热重载。用 Ctrl+C 停止，再运行 python -m main。

相关资源#