---
source_url: https://docs.dolphindb.cn/zh/plugins/plg_howtos.html
fetched_at: 2026-05-19T09:45:27Z
category: plugins
title: 插件介绍与使用
sha1: 5687fc5b808a1a159234645d637a44c30455c58b
---

# 插件介绍与使用

DolphinDB database 支持动态载入外部插件，以拓展系统功能。插件仅支持使用 C++ 编写，并且需要编译成 so 共享库或者 dll 共享库文件。

插件共享库依赖 include 目录中声明的类及接口，因此在编译插件时，必须确保插件分支应与 DolphinDB 版本的前三位数字相匹配，即若 DolphinDB 是 1.30.21.x 版本，插件应使用 1.30.21.x，若 DolphinDB 是 2.00.9.x 版本，插件应使用 2.00.9.x，其他版本依此类推。加载插件时也要保持版本匹配。

## 1. 目录结构

- **include**(./include) 目录包含了 DolphinDB 的核心数据结构的类声明和一些工具类声明，这些类是实现插件的重要基础工具。
- **demo**(./demo) 目录包含了一个 demo 插件的实现。
- **odbc**(./odbc) 与 **mysql** (./mysql) 等目录包含了 ODBC 与 MySQL 等插件的实现。

## 2. 插件格式

DolphinDB 使用一个文本文件来描述插件。该文件格式如下：首行描述插件名字和共享库文件名，其后每一行都描述一个共享库函数和 DolphinDB 函数的映射关系。

```dolphindb
module name, lib file, plugin version
function name in lib, function name in DolphinDB, function type, minParamCount, maxParamCount, isAggregate, isSequential
...
...
```

**解释**：

- module name: 模块名
- lib file: 共享文件库文件名
- plugin version: 插件版本号
- function name in lib: 共享库中导出的函数名
- function name in DolphinDB: DolphinDB 中的对应函数名
- function type: operator 或者 system，分别表示支持一个或两个参数的 Operator Functions 和支持任意数量参数的 System Functions
- minParamCount: 最少参数个数
- maxParamCount：最多参数个数
- isAggregate: 是否为聚合函数，可选值为 0（非聚合函数，默认值）或 1（聚合函数）
- isSequential：是否为序列函数，可选值为 0（非序列函数，默认值）或 1（序列函数）

## 3. 下载插件

DolphinDB 官方开发并发布了多种插件，用户可通过[插件市场](https://marketplace.dolphindb.cn/)直接下载安装。可通过如下步骤下载并安装插件：

(1) 在 DolphinDB 客户端中使用 [listRemotePlugins](https://docs.dolphindb.cn/zh/funcs/l/listRemotePlugins.html) 命令查看插件仓库中的插件信息。

```dolphindb
login("admin", "123456")
listRemotePlugins()  
```

注意：如果仅展示当前操作系统和 server 版本支持的插件。若无预期插件，您可以通过我们的 [GitHub 仓库](https://github.com/dolphindb/DolphinDBPlugin/tree/master)（选择对应版本分支）下载源代码自行编译。编译方法参考[第5章编译](#5-%E7%BC%96%E8%AF%91%E6%8F%92%E4%BB%B6)。

(2) 使用 [installPlugin](https://docs.dolphindb.cn/zh/funcs/i/installPlugin.html) 命令安装插件。

```dolphindb
installPlugin("mysql")
```

## 4. 下载插件

加载插件时需要确保插件分支应与 DolphinDB Server 版本的前三位数字相匹配，一旦版本号不匹配，在加载插件时会报错并停止加载。请在升级服务器后及时更新相应的插件，且不要随意修改已发布插件 txt 文件中的版本号。

### 4.1 通过 `loadPlugin` 函数加载插件

可使用 `loadPlugin` 函数加载外部插件。为该函数传入一个文件路径参数，指定插件的位置，例如：

```dolphindb
loadPlugin("/YOUR_SERVER_PATH/plugins/odbc/PluginODBC.txt");
```

注意：自 Server 版本 2.00.11 / 1.30.23 起，`loadPlugin` 支持直接使用插件名称（大小写敏感）。系统将根据插件名称和配置参数 `pluginDir` 自动加载插件。

```dolphindb
loadPlugin("odbc");
```

### 4.2 通过配置参数 *preloadModules* 加载插件

也可以通过配置参数 *preloadModules* 自动加载。需要确保预加载的插件必须实际存在，否则会在服务器启动时抛出异常。多个插件名称可使用英文逗号 `,` 分隔，例如：

```dolphindb
preloadModules=plugins::mysql,plugins::odbc
```

## 5. 编译插件

本节以开发一个 demo 插件为例，详细介绍如何编译插件。

### 5.1 环境准备与依赖

在开始编译 DolphinDB 插件前，请确保以下依赖项和环境配置已准备完毕：

#### 5.1.1 必备依赖

**C++ 编译器**：必须使用与 DolphinDB Server 版本兼容的 g++ 版本，详见下表。

**DolphinDB 头文件**：下载并使用与 DolphinDB Server 版本一致的插件分支中的 include/ 目录。

**DolphinDB 动态库**：Windows 平台编译时，需要用到 libDolphinDB.dll。

**编译器版本要求（按运行环境区分）**

| 操作系统类型 | DolphinDB Server 版本 | 推荐 g++ 版本 |
| --- | --- | --- |
| Linux/Linux\_JIT | 2.00.x、3.00.0.x、3.00.1.x | g++ 4.8.5 |
| Linux/Linux\_JIT | 3.00.2 及以上 | g++ 8.4.0 |
| Linux\_ABI | 2.00.x、3.00.0.x、3.00.1.x | g++ 6.2.0 |
| Linux\_ABI | 3.00.2 及以上 | g++ 8.4.0 |

#### 5.1.2 编译宏定义

编译插件时建议添加以下宏：

- `LOCKFREE_SYMBASE`：启用 SymbolBase 类的优化；
- `_GLIBCXX_USE_CXX11_ABI=0`：为了兼容老版本编译器，编译 libDolphinDB.so 时默认使用了 `_GLIBCXX_USE_CXX11_ABI=0` 选项，因此用户在编译插件时也应该加上该选项。若使用的是开启 `ABI=1` 的服务器，则可以省略；
- `LINUX`: 指定系统版本为 Linux。

### 5.2 定义插件描述文件

```dolphindb
demo,libPluginDemo.so,2.00.10
minmax,minmax,operator,1,1,0
foo,foo,system,1,1,0
```

以上描述文件 PluginDemo.txt 定义了一个名为 demo 的插件，共享库文件名为 libPluginDemo.so。插件版本号为2.00.10（请根据实际使用的插件版本进行修改）。该插件导出两个函数：

- `minmax`：在 DolphinDB 中注册为 `minmax`，类型为 operator，接受一个参数。
- `foo`：在 DolphinDB 中注册为 `foo`，类型为 system，同样接受一个参数。

写完描述文件之后，即可开始编写插件。内容请参考 [demo (*./demo*)](https://github.com/dolphindb/DolphinDBPlugin/tree/release200.15/demo) 文件夹内容。

### 5.3 编译插件

编译需要用到 [include](https://github.com/dolphindb/DolphinDBPlugin/tree/release200.15/include) 头文件，请提前选择正确的分支下载文件。编译步骤如下（以在 Linux 操作系统上编译为例）：

```dolphindb
cd demo
g++ -DLINUX -fPIC -std=c++11 -D_GLIBCXX_USE_CXX11_ABI=0 -DLOCKFREE_SYMBASE -c src/Demo.cpp -I../include -o Demo.o
g++ -fPIC -shared -o libPluginDemo.so Demo.o
```

编译成功后，目录下会生成一个名为 *libPluginDemo.so* 的共享文件。

在 DolphinDB 的控制台中输入下列命令加载插件并使用：

```dolphindb
>loadPlugin(PluginDemo.txt的路径); // 加载插件
(minmax,echo)
>use demo; // 引入插件的命名空间
>demo::minmax([12,3,4]); // 也可以使用minmax([12,3,4])
[3,12]
>demo::echo("foo");
foo
>echo(1);
1
```

更复杂的插件实现请参考 [odbc](https://github.com/dolphindb/DolphinDBPlugin/blob/release200.15/odbc) 目录下的内容。

## 6. 插件编译建议与故障排查

- 如果载入插件之后出现了 crash，可以采取尝试以下步骤。
  1. 确保 include(*./include*) 下的头文件和 *libDolphinDB.so* 或 *libDolphinDB.dll* 实现保持一致。
  2. 确保用于编译插件的 `gcc` 版本和编译 *libDolphinDB.so* 或 *libDolphinDB.dll* 的版本保持一致，以免出现不同版本的编译器 ABI 不兼容的问题。
  3. 插件与 DolphinDB server 在同一个进程中运行，若插件 crash，那整个系统就会 crash。因此在开发的插件时候要注意完善错误检测机制，除了插件函数所在线程可以抛出异常（server 在调用插件函数时俘获了异常），其他线程都必须自己俘获异常，并不得抛出异常。
  4. 请确保已正确添加编译宏，详见 [5.1.2 宏定义](#512-%E7%BC%96%E8%AF%91%E5%AE%8F%E5%AE%9A%E4%B9%89)。
- 如果编译时出现链接问题（undefined reference），并且包含 std::\_\_cxx11 字样，务必检查用于编译插件的 g++ 版本和\_GLIBCXX\_USE\_CXX11\_ABI 选项，确保与 DolphinDB 所使用的设置保持一致。
- 需要根据 DolphinDB 特性及版本号，正确选择 g++ 版本，详见编译器版本说明。
- 如果加载插件时报存在未定义的引用，可以尝试编译时链接 libDolphinDB.so，然后用 ld 命令查看是否还有其他未定义的引用。如果这时 ld 也会报错，则 DolphinDB 也无法正确加载插件。
