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

作者：袖梨 2026-07-29

安装 difyctl 最常见的问题并非命令太长，而是所装版本与正在使用的 Dify 服务器不匹配。自 Dify 1.15.0 版本开始，这个工具便随官方发布包提供，各版本的兼容范围都很明确。因此，安装前要先确认服务器版本，再按自身系统选择入口；安装后还必须执行版本检查，只有客户端版本、运行平台和兼容范围均可查看，才说明安装真正完成。

安装前需要核对 Dify 服务器版本以及系统与架构

操作位置：先从自己电脑的系统信息确定操作系统和处理器架构，再通过 Dify 管理后台或运维记录查明服务器版本。官方安装脚本在 macOS 和 Linux 上覆盖 x64、arm64 两种架构；至于 Windows，目前官方脚本的安装包仅有 windows-x64。

操作内容：服务器若运行最新正式版，可让安装脚本自动选择最新构建。服务器仍是旧版本时，应先记录完整发布标签，安装时用 DIFY_VERSION 参数指定相同版本。只有明确掌握 CLI 构建号时才使用 DIFYCTL_VERSION 参数，而且它仅在未设置 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，安装路径、对应的 Dify 版本和 difyctl 版本将被列出。下图记录的是实测的 macOS arm64 环境，对应关系为 Dify 1.16.0 与 0.2.0-alpha。

出问题怎么办：要是提示 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，再运行命令。变量不能像 shell 内联参数那样直接附在命令末尾，这是 PowerShell 的区别所在。

完成标准：校验结果与版本号、下载得到的 windows-x64 文件，以及 difyctl.exe 的最终安装位置，都会列在 PowerShell 中。故障处理：系统并非 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 配置错误。

执行版本检查，不要只看到「安装成功」便结束

操作位置：客户端自身无需配置 Dify 主机地址也能检查：另开终端或 PowerShell 窗口，直接运行 difyctl version。

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

完成标准：只要命令顺利执行并退出，Client 区块信息齐全，且平台、兼容范围符合预期，检查就通过。主机尚未配置时，Compatibility 为 unknown、Server 一栏为 skipped 都很正常。故障处理：如果客户端兼容范围不包含服务器版本，应重新执行官方安装脚本并设置正确的 DIFY_VERSION。看到 alpha 相关警告时，要将其视作预发布版本，是否用于生产环境应依据团队发布策略决定。

检查二进制文件架构与文件指纹

操作位置：若使用 macOS 或 Linux，应进入安装目录检查 difyctl 的文件类型及 SHA256；若是 Windows，则可执行 PowerShell 的 Get-FileHash。发布页校验和已由官方安装脚本自动比对，本步骤只是为了在电脑中保存一份核验记录。

操作内容：先核对文件类型是否匹配处理器架构，再保存 SHA256 哈希值。下图哈希仅对应本次下载的 0.2.0-alpha darwin-arm64 版本，不能视作全部平台和版本的固定值。手动下载时，必须逐项对照同一 Dify 发布页中的 checksums 文件。

完成标准：文件类型和架构均与设备匹配，计算所得哈希值也与同一发布版本清单一致。故障处理：架构错误时应删除文件并重新选择对应构建；哈希不一致则不能执行，需要从官方发布页重新下载，同时检查网络缓存或镜像源是否异常，绝不可使用可疑文件。

打开帮助页面，验证 CLI 能否正常运行

操作位置：确认版本无误后，继续在原终端运行 difyctl help。

操作内容：输出中至少应找到 version、use host、run app、get app、config、auth 这些入口，同时检查用法说明与命令列表。执行帮助命令既不要求登录，也不会动到你的 Dify 工作区内容。

完成标准：二进制文件能否在当前系统启动，可看终端结果判断：所有命令组都被正常列出，且没有动态库缺失或崩溃提示即可。故障处理：若版本命令可用而帮助命令异常，先确认两次执行的是同一路径下的文件，再重新安装匹配版本。若 shell 定位到旧版本路径，应清理 PATH 中重复目录，然后重开终端测试。

更新、版本切换与卸载方法

操作位置：仍从 Dify 官方「CLI / 安装」页面获取更新；若账号在卸载前处于登录状态，可先用 difyctl auth logout 清理当前会话。

操作内容：对应平台的官方安装脚本再次运行后，原路径中的二进制文件会在更新时被自动替换。如需指定 Dify 版本，须提前设置 DIFY_VERSION。默认安装下，macOS 和 Linux 要移除的是 .local/bin 中的 difyctl 文件；Windows 则需移除 LocalAppData 下完整的 difyctl 目录。

完成标准：若 difyctl version 在更新后给出目标版本，并且兼容范围匹配，说明更新成功；卸载是否完成，则以新终端中已找不到 difyctl 命令为准。故障处理：若更新后仍显示旧版本，应检查 PATH 是否指向另一份二进制文件。卸载不彻底时，先确定命令实际路径，再删除对应文件，避免误删存放其他工具的公共目录。