从零开发Dify插件并上传至插件市场：完整实战指南_阿奇CMS

Dify作为一款开源的LLM应用开发平台，其插件生态是实现功能扩展的核心载体。本文将以Python工具插件为例，为开发者提供从环境搭建、插件开发、本地测试到最终上线插件市场的全流程教学。无论你是想对接第三方API、扩展数据源，还是集成自定义模型，都能通过本文掌握Dify插件开发的规范与实操技巧，打造属于自己的可复用插件并分享给全球用户。

## 一、前置准备：打好开发基础
在开始开发前，需完成环境配置和知识储备，确保开发过程顺畅高效。

### 1.1 环境依赖配置
Dify插件开发对环境有明确要求，需提前安装以下工具：
- **核心运行环境**：Python ≥ 3.10（适配Dify后端技术栈，推荐3.10-3.12版本）、Node.js ≥ 18.x（若开发前端相关插件）；
- **包管理工具**：pip（Python包管理）、npm/yarn（前端依赖管理）；
- **辅助工具**：Git（版本控制）、Docker（本地部署Dify用于测试）、JSON校验工具（如在线JSON校验器，用于验证配置文件格式）。

### 1.2 核心文档与资源
- **官方开发文档**：[Dify插件开发指南](https://docs.dify.ai/zh-hans/plugins/develop)（必看，包含最新API规范和配置说明）；
- **插件市场规范**：[插件提交审核标准](https://docs.dify.ai/zh-hans/plugins/market)（明确上线要求，避免审核被拒）；
- **示例插件仓库**：Dify官方GitHub仓库中的[插件示例](https://github.com/langgenius/dify/tree/main/plugins)（参考成熟插件的结构和逻辑）。

### 1.3 明确插件类型
Dify插件分为三大类，开发前需根据需求确定方向：
| 插件类型       | 核心用途                          | 主流开发语言 | 适用场景                     |
|----------------|-----------------------------------|--------------|------------------------------|
| 数据源插件     | 对接MySQL、Elasticsearch等数据库  | Python       | 企业内部数据接入、自定义检索 |
| 工具插件       | 调用第三方API（天气、翻译、OCR）  | Python/Node.js | 扩展LLM的工具调用能力        |
| 模型插件       | 对接私有LLM、自定义模型服务       | Python       | 适配企业私有大模型部署       |

本文以**Python工具插件**为例，演示完整开发流程。

## 二、插件开发：从结构到代码
Dify插件有严格的目录结构和配置规范，需遵循官方Schema进行开发，确保插件能被Dify识别和加载。

### 2.1 搭建标准目录结构
一个合规的Dify插件需包含以下核心文件，目录结构如下：
```
my-weather-plugin/  # 插件根目录（小写字母+短横线，全局唯一）
├── plugin.json     # 插件核心配置（必选，Dify识别插件的关键）
├── main.py         # 业务逻辑实现（必选，插件功能入口）
├── requirements.txt # 第三方依赖声明（可选，如有外部包依赖）
├── README.md       # 插件使用文档（必选，上传市场需完善）
└── icon.png        # 插件图标（可选，建议512x512 PNG格式）
```

### 2.2 编写plugin.json配置文件
`plugin.json`是插件的“身份证”，包含插件的基本信息、配置项、操作定义等，需严格遵循JSON Schema规范。示例如下：
```json
{
  "id": "my-weather-plugin",
  "name": "实时天气查询插件",
  "description": "对接第三方天气API，查询全球城市实时温度、湿度、天气状况等信息",
  "version": "1.0.0",
  "author": "你的名字/团队名称",
  "email": "your-email@example.com",
  "url": "https://github.com/your-name/my-weather-plugin",
  "type": "tool",
  "logo": "icon.png",
  "tags": ["天气查询", "工具", "生活服务"],
  "runtime": "python3.10",
  "entry": "main.py",
  "config": [
    {
      "name": "weather_api_key",
      "label": "天气API密钥",
      "type": "secret",
      "required": true,
      "description": "从XX天气平台申请的API密钥，用于接口鉴权"
    }
  ],
  "operations": [
    {
      "name": "get_real_time_weather",
      "label": "查询实时天气",
      "description": "输入城市名称，返回该城市的实时温度、湿度、天气描述等信息",
      "parameters": [
        {
          "name": "city",
          "label": "城市名称",
          "type": "text",
          "required": true,
          "description": "支持国内城市（如北京、上海）和国外城市（如New York）"
        }
      ]
    }
  ]
}
```
**关键字段说明**：
- `id`：插件全局唯一标识，需提前在插件市场搜索确认无重复；
- `config`：插件全局配置项，用于存储敏感信息（如API密钥），用户在Dify后台配置；
- `operations`：插件提供的可调用功能，每个操作对应一个业务逻辑函数。

### 2.3 编写核心业务逻辑（main.py）
业务逻辑需实现Dify规定的接口，核心是`run`函数，作为插件的统一入口，根据操作名称分发处理逻辑。示例代码如下：
```python
import requests
from dify_plugin import PluginBase, PluginResponse

class WeatherPlugin(PluginBase):
    """天气查询插件核心类，封装业务逻辑"""
    def __init__(self, config: dict):
        super().__init__(config)
        self.api_key = self.config.get("weather_api_key")
        self.base_url = "https://api.weather.com/v1/current"

def get_real_time_weather(self, city: str) -> PluginResponse:
        """查询实时天气的核心方法"""
        # 校验配置
        if not self.api_key:
            return PluginResponse(success=False, message="请先配置天气API密钥")
        
        # 调用第三方天气API
        try:
            params = {
                "city": city,
                "key": self.api_key,
                "lang": "zh-CN"
            }
            response = requests.get(self.base_url, params=params, timeout=5)
            response.raise_for_status()  # 捕获HTTP请求错误
            data = response.json()

# 格式化返回结果
            result = {
                "城市": city,
                "实时温度(℃)": data.get("temperature"),
                "湿度(%)": data.get("humidity"),
                "天气状况": data.get("description"),
                "更新时间": data.get("update_time")
            }
            return PluginResponse(success=True, data=result)
        except requests.exceptions.RequestException as e:
            return PluginResponse(success=False, message=f"天气API调用失败：{str(e)}")
        except Exception as e:
            return PluginResponse(success=False, message=f"查询失败：{str(e)}")

# Dify插件统一入口函数，必须命名为run
def run(operation: str, params: dict, config: dict) -> PluginResponse:
    """
    插件入口函数，处理所有操作请求
    :param operation: 操作名称（对应plugin.json中的operations.name）
    :param params: 操作参数（用户传入的参数）
    :param config: 插件全局配置（用户在后台配置的信息）
    :return: PluginResponse格式的结果
    """
    plugin = WeatherPlugin(config)
    # 根据操作名称分发处理
    if operation == "get_real_time_weather":
        return plugin.get_real_time_weather(params.get("city"))
    else:
        return PluginResponse(success=False, message=f"不支持的操作类型：{operation}")
```
**核心规范**：
- 必须继承`PluginBase`基类，便于复用Dify提供的基础能力；
- 返回结果必须使用`PluginResponse`格式，包含`success`（布尔值）、`data`（成功数据）、`message`（错误信息）三个字段；
- 敏感信息通过`config`参数获取，禁止硬编码。

### 2.4 依赖管理（requirements.txt）
如果插件依赖第三方包（如`requests`），需在`requirements.txt`中声明，确保Dify安装插件时能自动安装依赖：
```txt
requests>=2.31.0
dify-plugin>=0.1.0
```

## 三、本地测试：确保插件功能正常
开发完成后，需在本地部署的Dify中进行测试，验证插件的配置、调用、返回结果是否符合预期。

### 3.1 部署本地Dify
推荐使用Docker快速部署Dify，步骤如下：
1. 安装Docker和Docker Compose；
2. 克隆Dify仓库：`git clone https://github.com/langgenius/dify.git`；
3. 进入目录并启动：`cd dify && docker-compose up -d`；
4. 访问`http://localhost:5001`，完成初始账号注册。

### 3.2 安装并配置插件
1. **打包插件**：将插件目录打包为ZIP文件，注意ZIP根目录直接包含`plugin.json`等核心文件，避免嵌套外层文件夹；
2. **上传插件**：登录Dify后台 → 插件 → 自定义插件 → 上传插件包；
3. **配置插件**：在插件列表中找到刚上传的插件，填写`weather_api_key`等全局配置项。

### 3.3 测试插件调用
1. 进入Dify应用编辑器，创建一个新的对话应用；
2. 在应用编辑器中，点击“添加工具”，选择刚安装的天气插件；
3. 配置工具调用参数（如城市=北京），点击“测试运行”，验证返回结果是否正确；
4. 查看日志：若调用失败，可通过`docker logs dify-api`查看详细报错信息，定位问题。

## 四、插件打包：符合市场上传规范
上传插件市场前，需确保打包格式符合要求，避免上传失败。

### 4.1 清理无用文件
删除插件目录中的临时文件、日志、缓存等无用内容，包括：
- `__pycache__`、`.git`、`.env`；
- 测试用例、本地配置文件；
- 操作系统自动生成的隐藏文件。

### 4.2 标准打包格式
1. 打包为ZIP文件，文件名与插件ID一致（如`my-weather-plugin.zip`）；
2. ZIP包结构：根目录直接包含`plugin.json`、`main.py`、`requirements.txt`、`README.md`等文件，无多余层级；
3. 编码格式：所有文件采用UTF-8编码，避免中文乱码。

## 五、上传插件市场：提交审核并上线
完成测试和打包后，即可将插件提交至Dify插件市场，供全球用户使用。

### 5.1 提交前准备
1. **完善README.md**：包含插件功能介绍、安装步骤、配置说明、使用示例、常见问题，便于用户快速上手；
2. **准备插件资源**：
   - 插件图标：建议512x512 PNG格式，透明背景，清晰体现插件功能；
   - 使用截图：截取插件配置、调用、返回结果的界面，帮助用户直观了解插件用法；
3. **合规检查**：
   - 确保插件无安全隐患（如硬编码密钥、未过滤用户输入）；
   - 确认调用的第三方API符合相关法律法规，不侵犯用户隐私。

### 5.2 提交流程
1. 访问Dify插件市场开发者平台：[plugins.dify.ai](https://plugins.dify.ai/)，使用Dify账号登录；
2. 进入“开发者中心”，点击“提交插件”；
3. 填写提交表单：
   - 基本信息：自动从`plugin.json`读取，可补充详细描述；
   - 上传资源：上传打包好的ZIP包、插件图标、README.md、使用截图；
4. 提交审核：Dify团队会对插件的功能完整性、安全性、文档规范性进行审核，周期约1-3个工作日；
5. 审核通过：插件将上线至Dify插件市场，所有用户可搜索、安装并使用你的插件。

## 六、关键注意事项与常见问题
### 6.1 核心注意事项
1. **唯一性**：插件ID需全局唯一，提交前务必在插件市场搜索确认，避免重复；
2. **安全性**：
   - 敏感信息必须通过`config`参数获取，禁止硬编码；
   - 对用户输入进行严格过滤，避免SQL注入、XSS等安全问题；
3. **兼容性**：确保插件兼容当前Dify稳定版，避免使用过时API；
4. **可维护性**：保留插件源码仓库，便于后续迭代更新，及时响应用户反馈。

### 6.2 常见问题排查
1. **插件上传失败**：检查ZIP包结构（根目录是否有`plugin.json`）、`plugin.json`格式（使用JSON校验工具验证）；
2. **插件调用报错**：查看Dify后台日志，排查依赖缺失、API调用失败、参数格式错误等问题；
3. **审核被拒**：根据审核反馈修改，常见原因包括文档不完整、功能存在bug、敏感信息处理不当等。

## 结语
开发Dify插件不仅能扩展Dify的功能边界，还能将你的解决方案分享给全球用户。遵循本文的流程和规范，从环境搭建到上线市场，一步步实现插件开发的全流程。后续可根据用户反馈持续迭代插件，优化功能和体验，为Dify生态贡献力量。如果开发过程中遇到问题，可参考Dify官方社区或GitHub仓库的issues，获取更多技术支持。

从零开发Dify插件并上传至插件市场：完整实战指南

搜索

热门推荐

最好用的vue拖拽组件vuedraggable在vue2和3下的使用

记录axios上传到阿里云OSS的两个小坑

Python使用PIL把一段文字完美像word一样排版

【开源】用于uni-app通过命令行打包自动上传到微信小程序的vite插件

Django安装百度统计referrer被禁用问题解决方案

阿奇支付接口文档

FastApi的初步推荐

阿奇WebSockets公共服务文档

FastApi用户指南

Django国际化makemessages报编码错误解决方案

标签