MacBook 安装 Dify 完整正确教程(2026官方最新适配版)

完全对齐 Dify 官方 Docker Compose 部署规范，适配 Intel / Apple Silicon（M1/M2/M3/M4）全系列 MacBook，覆盖终端操作+桌面可视化操作，提前规避所有常见踩坑点。

本教程完全对齐 Dify 官方 Docker Compose 部署规范，适配 Intel / Apple Silicon（M1/M2/M3/M4）全系列 MacBook，覆盖终端操作+桌面可视化操作，提前规避所有常见踩坑点。

一、部署前必读&最低要求

1.1 官方推荐部署方式Docker Compose 是 Dify 官方首推的本地部署方案，一键搞定所有依赖（PostgreSQL数据库、Redis缓存、向量数据库等），彻底避免环境冲突，Mac双芯片原生兼容。

1.2 最低配置要求• 系统：macOS 12.0 及以上• 芯片：Intel 或 Apple M 系列均可• 资源：Docker 虚拟机至少分配2核CPU + 8GB内存（低于该配置大概率出现服务启动失败）• 磁盘：至少预留20GB可用空间

二、前置环境安装（必须100%完成）

2.1 安装 Docker Desktop for Mac（核心依赖）

1. 下载安装包：访问Docker Desktop 官网，网站会自动识别你的Mac芯片，下载对应安装包

2. 安装：打开下载的.dmg文件，将Docker.app拖入「应用程序」文件夹

3. 启动与授权：从应用程序打开Docker Desktop，首次启动需同意服务协议，输入Mac开机密码授权安装组件。等待启动完成：顶部菜单栏出现小鲸鱼图标，且显示「Engine running」即为就绪

4.资源配置（必做，避免服务崩溃）：点击顶部小鲸鱼图标 → 选择「Settings」→ 进入「Resources」，CPUs调整为4核及以上，Memory调整为8GB及以上，Swap调整为2GB，点击「Apply & Restart」保存配置，等待Docker重启完成

5. 验证安装：打开「终端」（按下Command+空格，输入「终端」回车打开），依次执行以下2条命令：

# 验证Docker正常 docker --version  

# 验证Docker Compose正常 docker compose version

两条命令均正常输出版本号（无报错），说明Docker环境就绪。

2.2 安装 Git用于克隆Dify官方源码，Mac多数版本自带Git，先验证再安装：

git --version

若显示版本号则已安装，跳过后续步骤；若提示command not found，执行以下命令安装：

安装 Git（若未安装）

Mac 默认可能没有 Git，通过 Homebrew 安装（若未装 Homebrew，先执行下面的 Homebrew 安装命令）：

# 安装Homebrew（若未安装） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 

# 安装Git brew install git

三、获取Dify源码

终端执行以下命令，将Dify官方源码克隆到本地：

# 进入用户主目录 cd ~  

# 克隆官方源码（GitHub访问慢可使用下方国内加速地址） git clone https://github.com/langgenius/dify.git  

# 国内加速克隆地址（二选一即可） git clone https://gitee.com/mirrors/dify.git

克隆完成后，你的用户主目录下会出现dify文件夹。

四、生成.env配置文件（必做步骤）

Dify 依赖.env文件加载所有核心配置，仓库仅提供模板文件.env.example，必须复制生成正式的.env文件才能正常启动。

方式1：桌面可视化操作（无需终端命令）

完成后，docker文件夹内会出现.env文件，配置准备完成。

方式2：终端命令操作

# 进入docker部署目录 cd ~/dify/docker  

# 复制模板生成正式配置文件 cp .env.example .env

五、启动Dify服务

5.1 进入正确的部署目录所有Docker操作必须在~/dify/docker目录下执行，否则会报错找不到配置文件，终端执行：

cd ~/dify/docker

5.2 一键启动所有服务终端执行启动命令：

docker compose up -d

• 首次启动会自动下载所有依赖镜像，耗时3-10分钟，取决于你的网络速度• 终端最终输出Container xxx Started，说明所有容器创建完成

5.3 验证服务启动状态终端执行以下命令，查看所有容器状态：

docker compose ps

✅ 正常状态：所有容器的STATUS列均显示Up xxx seconds/minutes（运行中）❌ 异常状态：若有容器显示Exited或Restarting，参考文末常见问题排查。

六、访问Dify&初始化

6.1 正确的访问地址打开浏览器（Chrome/Safari均可），输入以下地址访问Dify：

http://127.0.0.1

💡 官方说明

新版Dify Docker部署默认使用80端口（浏览器默认端口，无需手动加:80），之前的8000端口已不再是默认端口，这是之前教程的核心错误点。若Mac出现localhost解析异常，优先使用127.0.0.1，稳定性100%。

6.2 初始化管理员账号

七、常用运维命令（新手必备）

⚠️ 注意

所有命令必须先执行cd ~/dify/docker进入部署目录后再执行。

八、自定义端口修改（可选）

若你的Mac 80端口被其他程序占用，可通过修改配置文件更换端口：

之后即可通过http://127.0.0.1:8000（你设置的端口）访问Dify。

九、常见问题&解决方案（覆盖99%的踩坑点）

9.1 报错：no configuration file provided: not found

原因：终端当前目录没有docker-compose.yml配置文件，99%是因为没有进入~/dify/docker目录解决：终端执行cd ~/dify/docker，再重新执行你的命令即可

9.2 容器启动失败/反复重启

常见原因1：Docker分配的内存不足解决：参考2.1的资源配置，将Docker内存调到8GB及以上，重启Docker后重新启动Dify

常见原因2：本地端口被占用解决：参考第八部分修改端口，或关闭占用端口的程序，重启服务

9.3 镜像下载慢/失败

原因：国内网络访问Docker官方镜像源受限

解决：配置Docker国内镜像加速1. 打开Docker Desktop → Settings → Docker Engine2. 在配置文件中添加以下镜像源：

"registry-mirrors": [   "https://docker.mirrors.ustc.edu.cn",   "https://hub-mirror.c.163.com" ]

9.4 访问127.0.0.1无响应

排查1：等待1-2分钟，服务完全启动有延迟

排查2：执行docker compose ps，确认所有容器都处于Up运行状态

排查3：执行docker compose logs -f api，查看API服务是否有报错

排查4：关闭浏览器的VPN/代理，避免无法访问本地地址

9.5 Apple M系列芯片兼容问题

现象：镜像拉取失败、容器启动报错

解决：Docker Desktop已原生适配Apple Silicon，只需确保下载对应芯片的安装包，开启「Settings → Features in Development → Use Rosetta for x86/amd64 emulation on Apple Silicon」选项，重启Docker即可。

附录

附录1：更新Dify到最新版本终端依次执行以下命令：

# 进入部署目录 cd ~/dify/docker  

# 停止当前服务 docker compose down  

# 拉取最新源码 cd ~/dify git pull  

# 同步最新配置文件 cd docker cp .env.example .env  

# 拉取最新镜像并启动 docker compose up -d

附录2：彻底卸载Dify（清空所有数据）终端依次执行以下命令：

# 进入部署目录 cd ~/dify/docker  

# 停止并删除所有容器、数据卷 docker compose down -v  

# 删除本地Dify源码目录 cd ~ rm -rf dify