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，卸载前则可以先退出登录。