aopstudio 的个人博客

问题背景

在无网或纯内网环境里为Dify安装插件，pip 源被限制为私有 PyPI 镜像或根本没有源可以访问，没有源肯定无法安装依赖，即便是私有PyPI镜像，也可能存在与PyPI总站的同步不完整或各种奇奇怪怪的情况，导致 pip install 因缺传递依赖而反复失败。

解决思路

思路很简单：在一台有公网的机器上，一次性下载插件所需的所有依赖包及其全部传递依赖，放到项目里，让pip 安装时直接索引到本地路径，不访问任何远程源。

操作步骤

第一步：完整下载依赖

前提：已经下载了插件的完整源码而不是difypkg安装包

具体操作步骤：

在公网机器上（不要求和部署机器相同平台，macOS 也行），把插件的顶层依赖和全部传递依赖一次性下载到 vendor/ 目录。

注意用 --platform 指定目标平台的架构，避免下载到不兼容的二进制包：

# 进入插件项目目录
cd dify-plugin-name

# 下载完整依赖树（只需写顶层依赖，pip download 自动处理传递依赖）
pip download dify_plugin~=0.5.0 \
  -d vendor/ \
  --platform manylinux2014_x86_64 \
  --python-version 3.12 \
  --only-binary=:all:

参数说明：

• pip download 默认递归下载所有传递依赖
• --platform manylinux2014_x86_64 确保下载的 wheel 兼容目标 Linux 环境
• --python-version 3.12 匹配目标 Python 版本（见 manifest.yaml 里的 runner.version）
• --only-binary=:all: 只下载预编译包，避免在无网环境触发编译

第二步：修改 requirements.txt

在原有依赖前面加两行：

--no-index
--find-links vendor/
dify_plugin~=0.5.0

• --no-index：pip 不访问任何远程索引
• --find-links vendor/：pip 从本地 vendor/ 目录找包

对于基础 Docker 镜像里已经装好的包（如 certifi、idna、requests），pip 会自动跳过，不需要放进 vendor/。

第三步：打包部署

在外层目录执行

dify plugin package ./dify-plugin-name

打包完成后上传到 Dify 实例即可。

项目结构

dify-plugin-name/
├── requirements.txt          # --no-index + --find-links vendor/
├── vendor/                   # 完整依赖树的 wheel 文件
│   ├── dify_plugin-0.5.1-py3-none-any.whl
│   ├── httpx-0.28.1-py3-none-any.whl       # 传递依赖，自动下载
│   ├── httpcore-1.0.9-py3-none-any.whl
│   ├── packaging-26.2-py3-none-any.whl
│   └── ...（所有传递依赖）
├── main.py
├── manifest.yaml
└── ...

常见问题

vendor/ 目录太大了怎么办？

vendor里的依赖包加起来大概 11MB，对一个插件项目来说不算大。如果你在意difypkg包的体积，可以在 .difyignore 里排除不需要的文件（如文档、缓存等），但不建议动 vendor/ 里的内容——少一个 wheel 都可能让构建崩掉。

基础镜像里已存在的无需安装

Dify安装插件的基础镜像里面通常已经预装了一些基础包，比如 certifi、idna、requests、tiktoken 等，那么在 vendor/ 里就不用重复放这些。

如果插件以后新增依赖怎么办？

重新在公网机器上跑一次第一步命令即可。新依赖会被自动下载进 vendor/，旧文件不用删——pip 会按版本选最合适的。