Dify difyctl 在 Windows、macOS 与 Linux 安装教程

装 difyctl 最容易踩的坑，真不是命令太长记不住，而是你装的版本跟自己用的 Dify 服务器对不上号。这个工具从 Dify 1.15.0 版本起就跟着官方发布包一起出了，每个版本的兼容范围都写得明明白白。动手之前，先把服务器版本确认好，再对应自己的系统选安装入口；装完一定要跑一遍版本检查，能看到客户端版本、运行平台和兼容范围，才算真的装到位了。

先确认好系统、架构和 Dify 服务器版本

操作上，第一步是去 Dify 管理后台或者运维记录里查清楚服务器的版本，再在自己电脑的系统信息里确认好操作系统和处理器架构。macOS 和 Linux 的官方安装脚本支持 x64、arm64 两种架构；Windows 目前的官方脚本只提供 windows-x64 版本的安装包。

核心步骤是：如果你的服务器用的是最新正式版，直接让安装脚本自动选最新的构建就行。要是服务器还在用旧版本，先把完整的发布标签记下来，安装的时候通过 DIFY_VERSION 参数指定成同一个版本即可。DIFYCTL_VERSION 这个参数只有你明确知道 CLI 构建号的时候才用，而且只有没设置 DIFY_VERSION 的时候它才会生效。

怎么算成功？系统、架构、服务器版本这三项都有明确的数值，不用靠猜来选安装包。如果出问题怎么办？要是查不到服务器版本，先别急着装，找管理员确认清楚再说；Windows on ARM、32 位 Windows 或者其他没列出来的环境，别硬套 x64 的命令。difyctl 的二进制文件本身不需要额外的运行时依赖，但安装脚本还是得联网，也需要用到一些系统自带的工具。

macOS 和 Linux：去官方安装页跑脚本安装

打开 Dify 官方文档里的「CLI / 安装」页面，切换到「macOS / Linux」标签，然后在终端里用普通用户身份登录。千万别从搜索结果摘要或者第三方教程里随便复制安装地址。

把页面里那行以 curl 开头的安装命令复制下来，贴到终端里执行。默认的安装目录是用户主目录下的 .local/bin；想装到别的目录，就在命令里设置 DIFYCTL_PREFIX 参数。如果服务器不是最新版，记得同时把 DIFY_VERSION 设好。官方脚本会自动识别你的系统和架构，从 Dify 的发布页下载二进制文件和校验和清单，核对完 SHA256 没问题了才会写到目标目录里。

怎么算成功？终端会显示下载的目标文件。出现 OK 提示后，difyctl 版本、对应的 Dify 版本和安装路径会紧接着列出来。下面图里是 macOS arm64 环境的实测结果：0.2.0-alpha，对应 Dify 1.16.0。

如果提示 curl、uname、sort 或者 SHA256 相关工具缺失，先按照脚本提示把对应的系统工具装上。如果是 macOS 系统提示 sort 不支持 -V 参数，得装个 coreutils 来提供这个功能。要是网络连不上或者碰到 GitHub API 限流，别反复重试命令；固定好 DIFY_VERSION 能减少接口查询次数，企业网络环境的话还要检查下能不能正常访问 GitHub Releases。

Windows：用 PowerShell 走官方入口安装

先打开 PowerShell，再打开 Dify 官方安装页的「Windows」标签。页面上会给一条以 irm 开头的 PowerShell 安装命令，默认会把 difyctl.exe 放到当前用户 LocalAppData 目录下的 difyctl/bin 文件夹里。

要做的第一件事，就是确认脚本是来自 Dify 官方仓库的，再执行页面上的命令。如果要匹配旧版本的服务器，得先在当前 PowerShell 会话里把 DIFY_VERSION 变量设好，再跑安装命令。注意，PowerShell 不能像 shell 那样把变量直接写在命令末尾当内联参数，必须先设变量，再执行安装。

怎么算成功？PowerShell 里会显示下载的 windows-x64 文件、校验结果、版本号，还有 difyctl.exe 最终的安装路径。如果系统不是 x64 架构，就别用这个脚本了；要是执行策略或者企业安全软件拦截了脚本，找管理员核验清楚是官方脚本再放行，千万别关了系统防护硬着装。要是校验和对不上，立刻把下载的文件删掉，绝对不能跳过校验继续用。

把安装目录加到系统 PATH 里

安装完成的时候，终端会在末尾打印安装路径和 PATH 相关提示。如果提示目录不在 PATH 里，说明文件已经装到电脑上了，只是新开的终端还找不到这个命令而已。

如果 macOS 用的是 zsh，就把 export PATH="$HOME/.local/bin:$PATH" 这行写到 .zshrc 文件里；Linux 的话就看你当前用的是什么 shell，写到对应的 .bashrc、.zshrc 或者其他配置文件里就行。要是只在当前终端窗口执行 export 命令，关了终端就失效了，不算永久配置。Windows 的话就在 PowerShell 里把 LocalAppData 下的 difyctl/bin 加到用户级的 PATH 里，弄完关了终端重开就好。

怎么算成功？新开一个终端，直接输 difyctl version 就能跑出结果，不用写完整的文件路径。要是还提示 command not found，先确认文件真的存在，再检查配置文件有没有被当前 shell 正常加载、PATH 里的目录拼写对不对。别靠反复安装来掩盖 PATH 配置错了的问题。

跑一下版本检查，别光看到「安装成功」就完事

新开一个终端或者 PowerShell 窗口，输入 difyctl version 就行。哪怕你还没配置 Dify 主机地址，也能做客户端本身的检查。

关键看输出里 Client 区块的 Version、Platform 和 Compat 这三项。Version 是 CLI 本身的构建版本，Platform 得跟你当前的系统和架构对得上，Compat 才是这个版本支持的 Dify 服务器版本范围。这次 macOS 实测的结果是 0.2.0-alpha、darwin/arm64，只兼容 Dify 1.16.0。

怎么算成功？命令正常执行完退出，Client 区块的信息是完整的，平台和兼容范围都符合预期。要是还没配置主机，Server 那栏显示 skipped、Compatibility 显示 unknown 都是正常的，完全不用担心。要是客户端的兼容范围里没有你服务器的版本，就重新跑官方安装脚本，设置好正确的 DIFY_VERSION；要是看到 alpha 相关的警告，就把它当预发布版本对待，生产环境要不要用得按团队的发布策略来定。

核对二进制文件的架构和文件指纹

macOS 或者 Linux 的话，进到安装目录里，对 difyctl 文件做文件类型和 SHA256 检查；Windows 可以用 PowerShell 的 Get-FileHash 命令。官方安装脚本其实已经自动跟发布页的校验和比对过了，这一步主要是为了在你自己的电脑上留个核验记录。

先确认文件类型跟你的处理器架构对得上，再把 SHA256 哈希值存下来。下面图里的哈希只是这次下载的 0.2.0-alpha darwin-arm64 版本的，可不能当成所有平台、所有版本的固定值。要是手动下载，必须拿同一个 Dify 发布页里的 checksums 文件一项一项比对清楚。

怎么算成功？文件类型、架构都跟你的设备对得上，算出来的哈希值跟同一发布版本的清单里的一致。架构不对就删掉文件，重新选对应的构建；哈希对不上就别执行了，重新从官方发布页下载，还要检查下是不是网络缓存或者镜像源的问题，绝对不能用可疑文件。

打开帮助页，确认 CLI 能正常跑起来

版本检查没问题的话，在同一个终端里输入 difyctl help 就行。

看看输出里的用法说明和命令列表，至少得能看到 auth、config、get app、run app、use host 和 version 这些入口。帮助命令不需要登录，也不会修改你的 Dify 工作区内容，放心用就好。

怎么算成功？终端正常列出所有命令组，没有崩溃或者动态库缺失的提示，就说明二进制文件能在你当前系统上正常启动。要是版本命令能跑，帮助命令却出问题，先确认你执行的是同一个路径下的文件，再重新安装匹配的版本就行；要是 shell 找到的是旧版本的路径，就把 PATH 里重复的目录清理掉，再重开终端试试。

怎么更新、切换版本和卸载

更新的话还是回到 Dify 官方的「CLI / 安装」页面就行；卸载之前要是已经登录过账号，先跑一下 difyctl auth logout 把当前会话清掉。

更新的时候重新跑对应平台的官方安装脚本就行，它会自动替换原来位置的二进制文件。要切换到指定的 Dify 版本，先把 DIFY_VERSION 设置好再跑。如果是 macOS 和 Linux 的默认安装，删掉 .local/bin 下的 difyctl 文件就行；Windows 默认安装的话，把 LocalAppData 下整个 difyctl 目录删掉就可以了。

怎么算成功？更新完之后，difyctl version 显示的是目标版本，兼容范围也对得上；卸载完之后，新开终端找不到 difyctl 命令就算成了。要是更新完还是显示旧版本，就检查下 PATH 是不是指向了另一份二进制文件。卸载不干净的话，先找到命令实际所在的路径，再删对应的文件，别误删了装着其他工具的公共目录。

difyctl 安装完成自查清单

• 已经确认过 Dify 服务器的版本，没直接把最新版 CLI 往旧版本服务器的环境里装。
• 你当前的系统和架构在官方支持范围内：macOS/Linux 是 x64 或 arm64，Windows 是 x64。
• 安装输出里有校验通过、版本号和最终路径的提示，没出现跳过 SHA256 校验异常的情况。
• 新开终端能直接运行 difyctl version，Client 区块里的平台和兼容范围都对得上。
• 预发布构建的 alpha 或者其他警告，已经考虑进生产环境的使用判断里了。
• difyctl help 能正常列出命令组，说明程序能在当前系统正常启动。
• 知道更新要重跑官方脚本，切换服务器版本要设 DIFY_VERSION，卸载之前可以先退出登录。