> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-release-1-15-0.mintlify.site/llms.txt
> Use this file 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

在 Dify 中打开 **插件** 页面，点击调试图标（**安装插件** 旁的小虫子图标）。弹窗会显示 **远程安装地址 host:port** 和一个 **API key**。

<Frame>
  ![远程调试插件](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png)
</Frame>

<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 theme={null}
INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=********-****-****-****-************
```

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

## 步骤 3：运行插件

在插件项目目录下：

```bash theme={null}
pip install -r requirements.txt
python -m main
```

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

## 步骤 4：验证安装

回到 Dify 的 **插件** 页面。插件会出现在列表中，并带有调试标记。工作空间的其他成员也能看到并使用它。

<Frame>
  ![插件已安装到工作空间](https://assets-docs.dify.ai/2024/12/ec26e5afc57bbfeb807719638f603807.png)
</Frame>

<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，再运行一次 `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)：调试完成后发布插件