> ## Documentation index
> Fetch the complete documentation index at: https://dify-docs.docs7.io/llms.txt
> Ask it with GET https://dify-docs.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# 插件调试

> 在本地运行开发中的插件，并将其挂载到在线 Dify 工作空间进行端到端测试，无需打包

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin)。

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

## 前置条件

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

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

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

<Tabs>
  <Tab title="Dify Cloud">
    地址类似 `debug-plugin.dify.dev:5003`。该 Key 为你的工作空间独有，任何持有它的人都能挂载插件，因此不要外泄。
  </Tab>
  <Tab title="自部署版">
    地址默认为 `127.0.0.1:5003`，由插件守护进程环境中的 `PLUGIN_REMOTE_INSTALLING_HOST` / `PLUGIN_REMOTE_INSTALLING_PORT` 配置。确保开发机能访问到 `5003` 端口。如果 Dify 在同一主机上以 Docker 运行，请使用守护进程容器的网桥 IP（或将端口暴露出来）。
  </Tab>
</Tabs>

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

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

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

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

## 步骤 3：运行插件

在插件项目目录下：

```bash
pip install -r requirements.txt
python -m main
```

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

## 步骤 4：验证安装

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

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

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

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

## 故障排查

<AccordionGroup>
  <Accordion title="连接被拒绝 / 无法访问地址">
    守护进程没有在 `REMOTE_INSTALL_URL` 填写的地址上监听。在自部署环境中，确认守护进程容器已设置 `PLUGIN_REMOTE_INSTALLING_ENABLED=true` 且 `5003` 端口已暴露。在云端，请再次核对所复制的 host:port 是否与 **调试** 中显示的完全一致。
  </Accordion>
  <Accordion title="插件已启动但始终不出现在插件列表中">
    最常见的原因是 `REMOTE_INSTALL_KEY` 失效或填错。从 **调试** 中复制当前的 Key 填入 `.env`，再运行一次 `python -m main`。同时确认守护进程日志显示了传入的注册请求。
  </Accordion>
  <Accordion title="`plugin_unique_identifier is not valid`">
    `manifest.yaml` 或 `provider/*.yaml` 中的 `author` 字段不是守护进程接受的值。将其设为你的 GitHub 用户名，然后重启。
  </Accordion>
  <Accordion title="改动不生效">
    每次修改后插件进程都需要重启，没有热重载。用 `Ctrl+C` 停止，再运行 `python -m main`。
  </Accordion>
</AccordionGroup>

## 相关资源

- [CLI](/zh/develop-plugin/getting-started/cli)：搭建插件并配置 `.env`
- [插件日志](/zh/develop-plugin/features-and-specs/plugin-types/plugin-logging)：从插件内部输出结构化日志
- [打包为本地文件并分享](/zh/develop-plugin/publishing/marketplace-listing/release-by-file)：调试完成后发布插件