在本地跑过 DIFY 的人应该都经历过这种抓狂时刻：官方文档说得明明白白，docker compose up -d一把梭，结果镜像拉取慢得像蜗牛，前端 Web 那个镜像更是动不动就构建到一半卡死，甚至直接报错退出。尤其当你改了 DIFY Web 端的前端代码，想打个本地镜像自测时，docker build往往要等上十几分钟，中间随便一点网络波动就前功尽弃。
我折腾了几天之后，把整个构建流程收进了一个 Makefile，现在一条make web就能稳定产出本地 WEB 镜像，顺带把构建卡顿、缓存失效、资源耗尽这类坑都提前堵死了。这篇文章就把这套思路完整拆给你看，从 Makefile 的写法到 docker build 的细节，再到遇到问题怎么排查，都会讲清楚。
1. DIFY 本地部署的血泪史：为什么默认方式不够用
1.1 现成镜像拉不动，构建又掉链子
DIFY 作为一个开源的 LLM 应用开发平台，官方推荐方式确实很省心：一个docker-compose.yaml把 API、Worker、Web、DB、Redis、Sandbox 全给你编排好了。可问题是，Web 前端镜像体积大、依赖多，默认情况下要先从公共镜像仓库拉取预构建镜像。
我自己的体验是，在容器环境正常的情况下，拉取 DIFY 相关的镜像经常遇到超时或者速度极慢。等了十几分钟，进度条还在 30% 附近转悠，最后给你一个网络超时的报错。如果你还碰到过类似your last request has been blocked for security purposes. please contact web这种提示，那通常就是访问境外资源时被目标端的防护机制弹回来了。
更麻烦的是，只要你有一点定制需求，比如改 Web 端 Logo、调页面样式、改交互逻辑，光拉现成镜像就不行了。你必须自己用 Dockerfile 构建一次web镜像。而 Web 这个服务又是整个 DIFY 里构建最重的环节——前端技术栈是 React/Next.js，依赖动辄上千个包，安装一次要拉取海量文件，网络一抖就废。
1.2 Makefile 能解决什么：稳定性、可重复、一键化
起初我也是手动敲docker build，命令长得记不住，参数漏一个就莫名其妙。更揪心的是，同样是构建 Web 镜像，每次失败原因都不一样：这次是依赖下载中断，下次是磁盘空间不够，再下次是 Docker 缓存把旧文件带了进去。
后来我把整个流程整理成了 Makefile。它的好处非常直接：
- 构建命令被固化成一个目标名，比如
make web，团队成员不用理解 docker 细节也能执行。 - 依赖关系由 make 自动分析，先准备什么、再做什么，顺序不会乱。
- 输出日志有统一的格式，出错时一眼能定位到是哪一步。
- 配置项全部收敛到文件顶端的一组变量里，改镜像名、改 tag、改构建参数，不用满世界找命令。
有人觉得 Makefile 是老古董，但在这个场景下，它比写一堆 shell 脚本更清晰，也比用 CI 平台的一堆插件更轻量。它本质上是把复杂的 Docker 构建工作流，翻译成了一句句人类读得懂的话。
2. Makefile 构建工作流的整体设计与选型思考
2.1 为什么不用纯 Shell 脚本
在决定 Makefile 之前，我其实先写了一个build-web.sh。Shell 脚本当然也能跑，但它有几个很难受的点。
第一，脚本是一行行顺序执行的，如果你想实现"只有代码变了才重新构建、依赖没变就跳过"这类逻辑，得自己写条件判断。第二，脚本的入口和参数传递不规范，时间一长，你自己都会被一堆./build-web.sh --tag=local --no-cache的参数搞晕。第三，打断重新执行时没有断点续跑的概念，失败了只能从头再来。
Makefile 的依赖模型天然适合构建场景。它通过目标（target）、依赖（prerequisite）和命令（recipe）三个元素组织任务。比如：
.PHONY: build build: web web: docker build -t $(WEB_IMAGE) -f ./web/Dockerfile ./web当你执行make build时，它会先检查web这个依赖目标是否满足，满足了才执行对应的构建命令。虽然这里我们用了.PHONY让目标每次都执行，但当你用真实文件作为目标时，make 会自动判断文件是否比依赖旧，决定要不要重建。这种"增量思维"正是构建流程需要的。
2.2 用 Makefile 管理 DIFY 的几种核心操作
我把 Makefile 设计成几个目标，覆盖了日常开发需要的高频动作：
| 目标 | 做的事情 | 典型使用场景 |
|---|---|---|
make web | 构建本地 Web 镜像 | 修改前端代码后重新出包 |
make up | 启动整套 DIFY 服务 | 本地全链路联调 |
make logs | 查看 Web 容器日志 | 排查启动失败或运行时错误 |
make prune | 清理构建缓存和悬空镜像 | 磁盘告急时紧急止血 |
make clean | 删除本地构建产物 | 彻底重来 |
核心思想是"高频操作短命令，危险操作也短命令但内容明确"。比如make clean里面明确写清楚会删掉哪些镜像，避免误操作。命名上追求一眼看懂，不要搞web-build、build-web这类绕口名称，团队里沟通起来也方便。
2.3 确定镜像命名与版本管理策略
构建之前，先想清楚镜像名和 tag 规则。DIFY 官方镜像名通常是langgenius/dify-web这种结构，但我们本地构建时不要直接用官方名，否则容易跟官方仓库镜像混淆。
我采用的方案是：
WEB_IMAGE ?= dify-web-local WEB_TAG ?= latest这样本地生成的完整镜像名是dify-web-local:latest。在docker-compose.yaml里，我可以把 web 服务的image字段临时改成这个名字，让docker compose up优先使用本地镜像，而不是去远程拉取。
为什么要用?=而不是=？因为?=只有在变量没有被预先赋值时才会赋值。这意味着你可以从命令行覆盖它：
make web WEB_TAG=v1.2.3这就给不同环境留了灵活出入口，默认值又足够安全。
3. 核心实现：从零写完一份可运行的 DIFY 构建 Makefile
3.1 项目目录结构说清楚
动手写 Makefile 之前，先确认 DIFY 项目的目录结构。我本地的路径大概是这样的：
dify-code/ ├── api/ # 后端 API 服务 ├── web/ # 前端 Web 服务 │ ├── Dockerfile │ ├── package.json │ └── ... ├── docker/ ├── docker-compose.yaml └── Makefile # 我们新建的注意，Makefile 放在整个仓库的根目录，因为docker build的上下文路径需要从根目录出发去指定。如果你把 Makefile 塞到web/里面，也不是不可以，但后续要管理整体服务编排时会别扭很多。
3.2 Makefile 的完整代码与逐段拆解
下面是我最终跑通的一份 Makefile，删掉了与业务无关的注释，保留了核心逻辑：
SHELL := /bin/bash # 基础配置 WEB_IMAGE ?= dify-web-local WEB_TAG ?= latest CONTAINER_NAME ?= dify-web-local COMPOSE_FILE := docker-compose.yaml .PHONY: help web logs up down prune clean rebuild help: ## 显示可用的 make 目标 @echo "可用的目标:" @echo " make web 构建本地 Web 镜像" @echo " make up 启动全部服务" @echo " make logs 查看 Web 容器日志" @echo " make down 停止服务" @echo " make prune 清理 docker 构建缓存（谨慎）" @echo " make clean 删除本地构建的 Web 镜像（谨慎）" @echo " make rebuild 强制重新构建（不使用缓存）" build-web: @echo ">>> 开始构建 Web 镜像: $(WEB_IMAGE):$(WEB_TAG)" docker build \ --build-arg NODE_ENV=production \ --file ./web/Dockerfile \ --tag $(WEB_IMAGE):$(WEB_TAG) \ ./web @echo ">>> 构建完成: $(WEB_IMAGE):$(WEB_TAG)" web: build-web @echo ">>> Web 镜像已就绪" up: docker compose -f $(COMPOSE_FILE) up -d @echo ">>> 服务已启动，执行 make logs 查看日志" logs: docker logs -f $(CONTAINER_NAME) down: docker compose -f $(COMPOSE_FILE) down rebuild: docker build --no-cache \ --build-arg NODE_ENV=production \ --file ./web/Dockerfile \ --tag $(WEB_IMAGE):$(WEB_TAG) \ ./web @echo ">>> 无缓存构建完成" prune: @echo ">>> 开始清理悬空镜像和构建缓存" docker builder prune -f docker image prune -f clean: docker rmi $(WEB_IMAGE):$(WEB_TAG) || true @echo ">>> 已删除本地构建镜像"逐段聊几个关键点。
第一行SHELL := /bin/bash是为了确保 make 执行命令时用的是 bash，而不是系统默认的 sh。因为 Docker 命令里面的换行续行写法在 bash 下最不容易出幺蛾子。:=是立即展开赋值，适合这种明确固定的值。
.PHONY这段我没有写全，只在help和命令式目标上用了。如果你把build-web设成.PHONY，每次执行都会强制跑构建命令；如果你希望借助 make 的文件时间戳判断是否重新构建，就不能把它设为.PHONY。这里我选择让它始终执行，因为 Docker 自身有层缓存，再加一层 make 的跳过意义不大，反而容易让人误判构建结果。
--build-arg NODE_ENV=production的作用是向 Dockerfile 传递构建参数。DIFY 的 Web Dockerfile 会根据NODE_ENV决定安装哪些依赖、执行什么构建命令，默认是生产环境构建。如果你在本地调试需要 dev 模式，可以单独加一个make dev-web目标，把参数改成NODE_ENV=development。
3.3 明确构建上下文：为什么--file和路径不能省
很多人构建卡住或者失败，根因是 Dockerfile 里的 COPY 指令找不到文件。这通常是因为构建上下文没用对。Docker 构建时，docker build后面那个路径参数就是上下文，Dockerfile 里的COPY只能访问上下文目录内的文件。
我写的./web就是上下文路径。Dockerfile 路径通过--file ./web/Dockerfile单独指定。这样一来，Dockerfile 在web/目录下，上下文也在web/，COPY 相对路径就不会错。
有个细节容易踩坑：如果 Dockerfile 里写了COPY ../package.json .，这种跳出上下文范围的写法在 Docker 里是禁止的。构建时会直接报错。DIFY 官方的 Dockerfile 设计规范，但你自己改 Dockerfile 时一定要避免这种写法。
3.4 让 docker compose 用上本地镜像
光把镜像构建出来还不够，还得让整个 DIFY 环境用上它。我的做法是准备一份本地专用的 compose 覆盖文件，比如docker-compose.local.yaml：
services: web: image: dify-web-local:latest然后启动时叠加使用：
docker compose -f docker-compose.yaml -f docker-compose.local.yaml up -d web把这个命令也写进 Makefile 的up目标就更顺手了。为什么不直接改官方docker-compose.yaml？因为那样会把官方镜像名覆盖掉，以后想切回官方镜像还得手动改回来，多账不划算。用 override 文件隔离本地改动，干净又安全。
4. 构建卡顿失败的根因分析与避坑指南
4.1 卡在依赖安装：前端 npm install 慢到令人发指
DIFY Web 镜像构建过程中，最耗时且最容易挂的就是npm install。这一步要拉取几百个依赖包，碰上网络波动，一个请求超时整个 RUN 就失败，前面全白干。
我在实际构建中试过几种解决办法，按有效程度排序：
第一，在 Dockerfile 里给 npm 配置可信的镜像源。DIFY 官方 Dockerfile 里通常有RUN npm install这种写法。你可以用构建参数把 registry 传进去，比如在 Dockerfile 里写：
ARG NPM_REGISTRY=https://registry.npmmirror.com RUN npm config set registry ${NPM_REGISTRY} && npm install然后在 Makefile 的docker build命令里加一个--build-arg NPM_REGISTRY=...。这样不需要改 Dockerfile 的最终逻辑，又能加速依赖下载。
第二，把依赖安装和源码复制分成两个 RUN，充分利用 Docker 层缓存。建议的 Dockerfile 逻辑是：先复制package.json和package-lock.json，执行npm install，再复制源码。这保证只要依赖文件没变，npm install的层就可以直接命中缓存，构建速度能快一个量级。
第三，给构建过程挂上 cache mount。用 BuildKit 的话，可以在 RUN 之前开启缓存挂载：
# syntax=docker/dockerfile:1.4 RUN --mount=type=cache,target=/root/.npm \ npm install这样 npm 的缓存可以跨构建复用，就算依赖层没命中，整体下载量也会少很多。
4.2 镜像构建体积失控：一个 Web 镜像好几个 G
Web 镜像体积大，根源在于构建过程中产生了大量中间文件和 node_modules。DIFY 官方 Dockerfile 一般已经做了多阶段构建，把编译后的静态文件复制到 nginx 镜像里，但我见到过一些二开项目把源码和 node_modules 一起打进去的，镜像体积直接爆炸。
一个简单有效的办法是检查.dockerignore。在web/目录下必须有一个.dockerignore，至少包含：
node_modules dist .git npm-debug.log这样构建上下文体积会小很多，上传到 dockerd 的耗时也会明显下降。构建上下文越大，构建前期的传输等待越久，这也是"卡住"的一种隐藏原因。
4.3 基础镜像拉取缓慢：把仓库地址想清楚
Dockerfile 里FROM node:20-alpine这类基础镜像也得从远程拉。有些基础镜像体积不小，拉取时网速不给力，整个构建就会卡在第一步。
这个问题的处理思路，和"构建卡顿"本身是类似的：
- 给 Docker 配置 registry mirror，让拉取
node、nginx这类基础镜像时走加速链路。至少我实测下来，配好 mirror 之后基础镜像的拉取时间能下降一大截。 - 如果你的项目在公司内网，通常可以配置公司内部自建的镜像仓库（比如 Harbor）做中转，这些仓库也会持有常用基础镜像缓存。
- 定好 base image tag 之后不要频繁升级 tag。比如
node:20-alpine不要随手改成node:21-alpine，否则每次都要拉新镜像。
4.4 硬件资源与磁盘问题：构建中途莫名被杀
构建很重的时候，Docker 容器要跑 npm、webpack，内存和 CPU 占用经常冲到很高。Docker Desktop 默认分配的 CPU/内存不一定扛得住，表现出来就是构建到一半容器被杀，或者 Docker 引擎直接无响应。
建议给 Docker 分配至少 4 核 CPU 和 6GB 内存。如果你用 Docker Desktop，这个可以在 Settings -> Resources 里调。如果你是 Linux 服务器上用 Docker，则要留意系统本身的内存和 swap。
另外，镜像层多了以后，Docker 的构建缓存和悬空镜像会把磁盘塞满。一个常见的报错是no space left on device，但你的磁盘明明看起来还有空间。这时多半是 inode 占满了，或者 Docker 家目录所在的挂载盘爆了。用下面的命令快速排查：
df -h df -i docker system df解决方案就是清理缓存：
make prune docker builder prune -a # 更激进，会清空所有构建缓存4.5 多架构构建陷阱：ARM Mac 上构建 X86 镜像等于慢动作
这是一个非常隐蔽的坑。如果你的开发机是 Apple Silicon（M1/M2/M3），默认docker build会构建 ARM64 架构的镜像。但当你需要部署到 X86 服务器上时，就得用buildx做多架构构建，或者指定--platform linux/amd64。
问题在于，模拟 x86 环境下运行 npm install 和前端构建，性能会大打折扣，一个原本两分钟的构建可能变成十几分钟。表现上就是"卡住了、特别慢"。
如果你真的需要跨架构构建，建议直接在构建命令里显式指定平台，并在 Makefile 里加一个变量：
BUILD_PLATFORM ?= linux/amd64构建时：
docker buildx build --platform $(BUILD_PLATFORM) --load ...我个人建议，如果不是必须，优先在本机原生的架构上构建，然后用 tag 区分。比如在 M 芯片的机器上构建dify-web-local:arm64，在 X86 机器上构建dify-web-local:amd64。不要在本地模拟对方架构，浪费生命。
5. 实操过程中的常见问题与排查技巧实录
5.1 构建一直卡在等待状态，日志没有任何输出
遇到这种场面，先别慌。执行下面几步：
# 查看当前构建是否还活着 ps aux | grep docker build # 查看 Docker 引擎的资源占用 docker system df # 看看 dockerd 日志，尤其是最后的错误输出 journalctl -u docker | tail -50如果是 Docker Desktop 环境，直接把 Docker 重启一次再构建，很多时候就好了。这种情况多半是引擎侧的资源锁或者缓存索引坏了，不是代码问题。
5.2 make 报错：makefile: No targets specified and no makefile found
这个一般是当前目录没找对，Makefile 不在你执行的目录下。执行pwd确认一下。还有一种情况是 Makefile 文件名写成了Makefile.txt或者makefile.bak，macOS 或 Windows 上特别容易发生。make 只会识别Makefile、makefile和GNUmakefile这几个名字，其他名字不会被自动读取。
Windows 上还有个小坑：换行符必须是 LF，不能用 CRLF。如果你的 Makefile 在 Windows 上用记事本编辑过，执行时可能出现各种怪异报错。用 VSCode 或 Notepad++ 把 EOL 改成 LF 再试。
5.3 构建更新后页面总是旧版本
这是前端构建里最经典的缓存问题。注意两个层面。
第一，浏览器层面。DIFY Web 是 Next.js 应用，构建出的静态资源带有 hash，浏览器一般会自动拉取新版本。但 nginx 配置如果对index.html做了强缓存，就会出现更新后还是旧页面的情况。你可以给容器的 nginx 配置添加Cache-Control: no-cache针对 html，而静态资源保留长缓存。
第二，镜像层面。如果你反复docker build，旧镜像层可能被复用。当package-lock.json没变但其他代码变了，npm 那步通常会命中缓存，这是我们想要的。但如果你改了 Dockerfile 里的某些指令，比如环境变量、基础镜像 tag，后续层级的缓存就可能全部失效。想彻底验证从零构建是否顺利，用一次无缓存构建：
make rebuild5.4 常见报错速查表
| 报错/现象 | 最可能原因 | 解决方法 |
|---|---|---|
Get https://registry-1.docker.io/v2/: i/o timeout | 基础镜像仓库访问超时 | 配置 registry mirror，或提前把基础镜像拉取好再构建 |
npm ERR! network timeout | npm 源不稳定 | Dockerfile 里切换 npm registry，开启 cache mount |
COPY failed: file not found in build context | Dockerfile COPY 路径超出上下文 | 调整上下文路径，或把所需文件放入同一个目录 |
no space left on device | 磁盘或 inode 满 | docker system prune、docker builder prune，检查挂载盘容量 |
make: ⚠️ Target ... gave errors | 构建命令返回非零退出码 | 看上方具体命令的日志，定位真正的失败步骤 |
| 构建成功但启动容器后 502 | Web 构建产物有问题或 nginx 配置不对 | 查看容器日志，确认是否缺少静态文件或转发地址错误 |
6. 把 Makefile 融入更大的部署流程
6.1 本地开发与团队协作的分工
Makefile 不只是给自己用的。如果你的团队里有人负责 DIFY 平台运维，有人二开前端，那 Makefile 就是团队约定的"操作面板"。新同事入职，不需要理解 Docker 细节，只需要知道make web构建镜像、make up启动服务。这比甩给他一段 wiki 更高效。
我习惯在 Makefile 里写好help目标，然后让它成为默认目标：
.DEFAULT_GOAL := help执行make时自动打印所有可用的目标。这个细节成本很低，但对提高团队使用体验非常有帮助。
6.2 与 CI/CD 衔接的注意点
虽然本地构建用 Makefile，但 CI 上也可以用同样的目标。比如在 GitLab CI 或 GitHub Actions 里直接跑make web，把构建产物推到私有仓库。要注意的是，CI 环境通常没有 Docker Desktop，使用的是 docker CLI 加远程引擎或 DinD，构建缓存策略要单独配置。
另外，CI 中别用交互式的容器名，每次构建都用新的短命容器。Makefile 里的CONTAINER_NAME主要服务于本地日志查看和启动，CI 里可以不使用 compose，直接通过 CI 内置服务来跑测试。
6.3 更进一步：把 Dockerfile 优化和 Makefile 优化同步进行
Makefile 只是流程层，真正的快慢还是看 Dockerfile 本身。这里我留了一个建议：每次改 Makefile 的构建逻辑，顺带看一眼 Dockerfile 的层设计。
一个健康的 Web 构建 Dockerfile，大体是这样的结构：
FROM node:20-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm \ npm install COPY . . RUN npm run build FROM nginx:alpine COPY --from=build /app/dist /usr/share/nginx/html这个多阶段结构天然支持缓存利用和镜像瘦身。如果你发现自己的本地镜像体积特别大，第一反应应该是 Dockerfile 结构出了问题，而不是盲目加 Makefile 参数。
写在最后的实操心得
这套 Makefile 我用了大概三周，期间遇到过各种奇怪问题，但只要有统一入口和清晰的日志，问题定位都快了很多。个人最大的感受是，构建卡顿这种事，你越靠"人肉重试"，越容易陷入无意义的重复劳动；反而把依赖缓存、镜像源配置、资源配额这些基础工作做扎实后，构建失败率能从天天下滑到偶尔一次。
最后再分享一个细节：我在 Makefile 里把所有故意可能"失败"的命令都加了|| true或者明确的错误提示，比如docker rmi删除不存在的镜像时直接忽略。但真正重要的构建命令绝对不能加|| true，不然 CI 里报错了你都不知道，所有自动化流程都会静默失败。这个边界，拿捏清楚比多写几个目标重要多了。
