Docker Compose 升级应用后，旧覆盖文件导致服务缺少 image 或 build

更新自托管应用的主 Compose 文件后，启动或校验配置报出：

service "worker" has neither an image nor a build context specified: invalid compose project

主文件里明明没有 worker，报错却一直指向它。检查一起加载的覆盖文件：旧版本曾有这个服务，主文件升级后将它删除或合并到了其他服务，但本地覆盖文件仍留下了它的端口、环境变量或挂载配置。

覆盖文件可以向项目添加新服务，并非只能修改主文件里已有的服务。因此，残留的 worker 不会被自动忽略；合并后的模型中，它仍是一个服务，只是失去了原先从主文件继承的 image 或 build。

这只解释“主文件已经移除服务，覆盖文件仍保留同名片段”的情况。如果主文件本身就缺少镜像、镜像变量展开为空，或者选错了主文件，也可能出现类似错误，不能一概删除报错的服务。

对比主文件单独校验与合并校验

下面使用 compose.yaml 和 compose.override.yaml 作为示例文件名。实际项目若使用 docker-compose.yml、其他覆盖文件或部署脚本，要按真实加载顺序替换；保留原有的项目目录、环境文件等选项。

docker compose -f compose.yaml config
docker compose -f compose.yaml -f compose.override.yaml config

第一条明确只选主文件，第二条按顺序合并覆盖文件。这里只渲染和校验配置，不启动容器。若第一条通过、第二条报某个旧服务没有镜像，再对照两个文件中的 services 名称，就能缩小到合并带入的配置。

默认使用这两个文件名时，未指定 -f 的 Compose 会自动读取同目录的覆盖文件。其他部署还可能通过 COMPOSE_FILE 或一组 -f 加载更多文件；应逐个加入校验，找出从哪一个文件开始出现旧服务。不要只看编辑器里当前打开的主文件。

config 输出可能包含展开后的环境变量和路径，保存或分享时需要检查敏感内容。不要用跳过一致性检查的选项，把“能打印 YAML”误当成模型已经有效。

旧服务片段怎样变成无镜像服务

下面是一组用于说明合并关系的配置，不是应用部署模板。主文件只保留了 web：

services:
  web:
    image: busybox:1.36
    command: ["echo", "configuration example"]

旧覆盖文件却仍然包含 worker：

services:
  worker:
    environment:
      LOG_LEVEL: debug

合并时，worker 会作为额外服务留下。它只有环境变量，既没有镜像也没有构建上下文，因而不能作为完整服务运行。单独运行覆盖文件的校验也可能报错，因为覆盖文件本来就可以只是配置片段，应该与对应版本的主文件一起判断。

给 worker 随便补一个镜像虽然可能绕过这项校验，却会重新创建一个应用已经不再需要的服务。应确认旧服务的职责是否已经迁移，以及这些自定义配置现在由谁接收。

迁移仍需要的设置，再移除失效片段

编辑前保存主文件、覆盖文件和相关环境文件的副本，并记录当前应用版本。涉及数据挂载的项目，还应确认应用数据备份可恢复；配置文件副本不能代替数据备份。

对照应用这次升级的迁移说明，逐项处理旧服务里的设置。已经取消的设置可以移除；仍然需要的设置，只有确认新服务支持同样的变量、端口或容器路径后，才能迁过去。

例如，只有在新服务 web 确实支持相同的 LOG_LEVEL 设置时，上面的覆盖文件才可以改为：

services:
  web:
    environment:
      LOG_LEVEL: debug

这个例子仅展示服务键名的迁移。不能把真实应用里所有旧服务名都替换成 web，也不能把多份挂载和端口列表直接拼到一起。

尤其要核对持久化目录：宿主机来源路径必须仍指向原数据，容器内目标路径必须符合新镜像要求。多文件合并时，相对路径通常以首个主 Compose 文件为基准，不是以覆盖文件所在目录为基准。迁移过程中顺便移动文件，可能让同一条相对路径指向另一个位置。

如果覆盖文件还包含有效的代理端口、证书或其他自定义设置，只移除确认失效的服务片段，保留其余内容。整份删除可能让配置校验通过，却丢失应用正常对外服务所需的设置。

校验服务清单和挂载后，再应用变更

修改完成后，使用部署时同一组文件重新检查：

docker compose -f compose.yaml -f compose.override.yaml config --quiet
docker compose -f compose.yaml -f compose.override.yaml config --services
docker compose -f compose.yaml -f compose.override.yaml config

第一条检查模型是否有效，第二条核对旧服务是否已经消失，第三条检查新服务的镜像、端口和挂载是否仍符合预期。仅仅不再出现缺镜像错误，还不足以确认数据路径正确。

配置确认后，按应用对应版本的升级流程，在允许中断服务的窗口应用变更。若应用要求专用更新脚本、数据库迁移或特定启动顺序，应继续遵守这些步骤，不把一次 Compose 校验当作完整升级。

启动后检查服务状态、日志和实际功能，并确认历史数据仍可见。不要用删除数据卷、清空 Docker 数据目录或重新安装来修复一个覆盖文件残留问题。

尚未启动新版本时，可以恢复备份的配置并重新校验。已经运行过新版本、尤其是执行过数据库迁移时，恢复旧覆盖文件不会撤销数据变化；回退必须使用匹配的应用版本、配置和数据恢复方案。也不要为清理旧服务就直接执行带删除卷选项的命令。