docker-compose.yml执行docker compose up -d报错：services.networks must be a mapping

问题描述 #

执行命令：

docker compose up -d

收到错误提示：

validating /home/arl114/jenkins/docker-compose.yml: services.networks must be a mapping

使用YAML校验工具显示配置文件格式有效，但容器创建失败。

原配置文件内容：

version: '3'
services:
  jenkins:
    container_name: jenkins
    image: jenkins/jenkins
  ports:
    - "8080:8080"
  volumes:
    - "$PWD/jenkins_home:/var/jenkins_home"
  networks:
    - net
networks:
  net:

解决方案 #

问题出在YAML缩进错误，ports、volumes、networks属于jenkins服务的专属配置项，需要缩进至jenkins节点下，而非和jenkins同级。

修正后的配置文件：

version: '3'
services:
  jenkins:
    container_name: jenkins
    image: jenkins/jenkins
    ports:
      - "8080:8080"
    volumes:
      - "$PWD/jenkins_home:/var/jenkins_home"
    networks:
      - net
networks:
  net:

原因说明 #

原配置中，ports、volumes、networks被错误定义在services根节点下，而非具体的jenkins服务节点内。Docker Compose的语法规则要求：services节点下只能包含各个服务的独立映射配置，不能直接存在ports、networks这类字段。

YAML校验工具仅检查语法格式是否合法，不会验证Docker Compose的语义规则，因此会出现“格式有效但运行报错”的矛盾情况。

内容的提问来源于stack exchange，提问作者Adam Levin