插件调试

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

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

前置条件

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

步骤 1：获取调试 URL 和 Key

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

Dify Cloud
自部署版

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

地址默认为 127.0.0.1:5003，由插件守护进程环境中的 PLUGIN_REMOTE_INSTALLING_HOST / PLUGIN_REMOTE_INSTALLING_PORT 配置。确保开发机能访问到 5003 端口。如果 Dify 在同一主机上以 Docker 运行，请使用守护进程容器的网桥 IP（或将端口暴露出来）。

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

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

INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=********-****-****-****-************

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

步骤 3：运行插件

在插件项目目录下：

pip install -r requirements.txt
python -m main

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

步骤 4：验证安装

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

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

工作空间的其他成员也能看到并使用它，前提是你的本地进程保持连接。像调用其他插件一样触发它：从工作流节点调用、在 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。

快速开始

特性与规范

开发指南与示例

发布

前置条件

步骤 1：获取调试 URL 和 Key

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

步骤 3：运行插件

步骤 4：验证安装

故障排查

相关资源

​前置条件

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

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

​步骤 3：运行插件

​步骤 4：验证安装

​故障排查

​相关资源

前置条件

步骤 1：获取调试 URL 和 Key

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

步骤 3：运行插件

步骤 4：验证安装

故障排查

相关资源