> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 构建、打包、调试和安装 Dify 插件时的常见问题与解决方法

## 打包与安装

### 为什么 `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. **生产环境推荐**：为插件包签名。参见 [第三方签名校验](/zh/3.0.x/develop/plugins/publishing/standards/third-party-signature-verification.md)。
2. **开发与可信的内部使用**：关闭校验。在 `docker/.env` 中添加 `FORCE_VERIFYING_SIGNATURE=false`，然后重启：

   ```bash theme={null}
   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` 格式（而非分开的变量）。完整排查清单参见 [插件调试](/zh/3.0.x/develop/plugins/features-and-specs/plugin-types/remote-debug-a-plugin.md)。

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

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

## 市场发布

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

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

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

参见 [跟进 PR 检查与审核](/zh/3.0.x/develop/plugins/publishing/marketplace-listing/submit-plugin-to-marketplace.md#after-you-submit)，根据检查结果判断是否需要处理。

### 市场审核需要多长时间？

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

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

在 `manifest.yaml` 中提高 `version`，重新构建软件包，再使用新的 `.difypkg` 向 `langgenius/dify-plugins` 提交 PR。除非维护者另有要求，否则保留仓库中已发布的软件包。参见 [提交 Marketplace Pull Request](/zh/3.0.x/develop/plugins/publishing/marketplace-listing/submit-plugin-to-marketplace.md#选择提交类型)。

### 我可以让插件变现吗？

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

## 存储与限制

### 插件日志在哪里？

自部署：插件守护进程的容器日志（`docker compose logs plugin_daemon`）。云端：仅在远程调试期间于工作空间的插件调试面板中可见，持久化日志不会在界面中暴露。结构化输出请使用 [插件日志](/zh/3.0.x/develop/plugins/features-and-specs/plugin-types/plugin-logging.md)。

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

是。KV 存储 API（`self.session.storage`）按每个插件在每个工作空间的安装实例隔离。使用同一插件的两个工作空间不会共享键。参见 [持久化存储（KV）](/zh/3.0.x/develop/plugins/features-and-specs/plugin-types/persistent-storage-kv.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.