常见问题

​

打包与安装

​

为什么 dify plugin package 失败并提示 plugin_unique_identifier is not valid？

manifest.yaml 以及所有 provider/*.yaml 文件中的 author 字段必须与你的 GitHub 用户名一致。在每个文件中更新该字段，用 dify plugin package 重新打包，然后重新安装。

​

为什么出现 plugin verification has been enabled, and the plugin you want to install has a bad signature？

自部署 Dify 默认对插件包强制执行签名校验。有两种处理方式：

1. 生产环境推荐：为插件包签名。参见 第三方签名校验。
2. 开发与可信的内部使用：关闭校验。在 docker/.env 中添加 FORCE_VERIFYING_SIGNATURE=false，然后重启：
   cd docker
   docker compose down
   docker compose up -d
   
   这样可安装任意未签名的插件，包括市场之外的插件，因此仅应在你可控的环境中这样做。

​

.difypkg 文件有大小上限吗？

有。插件守护进程会拒绝超过可配置上限（默认 50MB）的插件包。如果你要分发较大的模型权重或静态资源，请将其托管在外部并在首次使用时下载，或就提高市场插件的上限事宜联系 Dify 支持团队。

​

我的插件需要 Python 3.13，可以更改运行时吗？

不可以。插件运行在受管的 Python 3.12 环境中。请将依赖固定为兼容 3.12 的版本。守护进程不会采用 manifest.yaml 中指定的其他运行时版本。

​

远程调试

​

为什么我的插件已启动，却始终未出现在工作空间中？

按顺序检查三处：(1) 守护进程日志中显示有注册请求，(2) REMOTE_INSTALL_KEY 与调试对话框中显示的一致，(3) REMOTE_INSTALL_URL 使用 host:port 格式（而非分开的变量）。完整排查清单参见 插件调试。

​

我的代码改动会热重载吗？

不会。每次改动后，用 Ctrl+C 停止插件进程，再重新运行 python -m main。

​

OAuth 与凭据

​

在上游 OAuth 提供方处应配置什么回调 URL？

工具类插件使用 https://<your-dify-host>/console/api/oauth/plugin/<author>/<plugin-name>/tool/callback。确切的格式会显示在 Dify 内插件的 OAuth 设置卡片中。

​

为什么我的 OAuth 令牌不刷新？

只要你的提供方实现从首次授权中返回了有效的 refresh_token，插件 SDK 就会在令牌过期时自动刷新。请确认 OAuthCredentials.refresh_token 已被填充，且已实现 _oauth_refresh_credentials 方法。

​

市场发布

​

为什么我的市场 PR 被自动检查驳回了？

Marketplace 工作流会检查软件包、元数据、依赖、披露和安装。具体检查项会随仓库持续演进。常见阻断原因包括：

• 变更多个 .difypkg：每个 PR 只提交 1 个插件软件包。
• PR 模板或风险选择不完整：保留所有模板章节，只选 1 个风险等级，并披露敏感能力。
• 包含密钥、开发产物或未说明的二进制文件：从软件包中删除这些内容并重新构建。
• manifest、README、隐私、源码或联系信息无效：保持软件包元数据与 PR 声明一致。
• 依赖策略失败：Python 插件必须使用 dify-plugin >= 0.9.0，并解决安装与漏洞问题。
• 版本重复或安装/打包测试失败：提高版本，重新构建，并使用当前 daemon 测试。

参见 跟进 PR 检查与审核，根据检查结果判断是否需要处理。

​

市场审核需要多长时间？

审核时间没有固定承诺。提供完整的软件包证据、填写完整的 PR 模板并解决 CI 结果，可减少审核往返。关注 PR 中的审核评论，并在同一分支持续修改。

​

如何为市场上已有的插件发布更新？

在 manifest.yaml 中提高 version，重新构建软件包，再使用新的 .difypkg 向 langgenius/dify-plugins 提交 PR。除非维护者另有要求，否则保留仓库中已发布的软件包。参见 提交 Marketplace Pull Request。

​

我可以让插件变现吗？

暂时不可以。市场目前仅接受免费插件。后续的定价政策将另行公布。

​

存储与限制

​

插件日志在哪里？

自部署：插件守护进程的容器日志（docker compose logs plugin_daemon）。云端：仅在远程调试期间于工作空间的插件调试面板中可见，持久化日志不会在界面中暴露。结构化输出请使用 插件日志。

​

插件存储是按工作空间隔离的吗？

是。KV 存储 API（self.session.storage）按每个插件在每个工作空间的安装实例隔离。使用同一插件的两个工作空间不会共享键。参见 持久化存储（KV）。