docker-compose config 是校验配置文件语法合法性的第一步，成功输出规范化 yaml 表示结构正确、缩进合规、字段可用、版本匹配；报错则精准定位问题位置，且不启动任何容器。

直接看配置文件本身是否合法，再结合启动日志定位具体哪一行、哪个字段出问题，是最高效的方式。

用 docker-compose config 验证语法

这是第一步，也是最关键的一步。它不启动任何容器，只解析并输出最终生效的配置结构：

• 运行 docker-compose config，如果输出完整 YAML 内容，说明语法基本正确
• 若报错，会明确指出错误位置，比如 “found character '\t' that cannot start any token”（用了制表符缩进）、“mapping values are not allowed here”（冒号后少了空格）
• 常见陷阱：YAML 要求用空格缩进（推荐两个），不能混用 Tab；环境变量引用 ${VAR} 中 VAR 名称拼写错误或未定义；布尔值写成 true/false 而不是 True/False（部分版本敏感）

查端口、镜像、路径三类硬依赖

很多“配置错误”其实是外部资源不可用导致的启动失败，表现像配置问题，实则是环境缺失：

minimax-mcp-docker版（适配极空间）

MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。

下载

• 端口冲突：错误提示含 “port is already allocated”。用 lsof -i :80 或 netstat -tulnp | grep :80 查谁占着，再决定是杀进程还是改 compose 里的 ports
• 镜像拉取失败：提示 “pull access denied” 或 “no such image”。确认镜像名拼写、标签是否存在，私有仓库是否已 docker login；本地构建服务则检查 build.context 路径是否存在、Dockerfile 是否在指定位置
• 挂载路径错误：如 “ERROR: for web Cannot create container for service web: invalid mount config”。检查 volumes 中宿主机路径是否真实存在、权限是否可读写，特别是 Windows/macOS 下路径分隔符或盘符是否写错（类似 APMServ 里 E:/ 改成 D:/ 的情况）

看日志，锁定失败服务的具体原因

docker-compose up -d 后看似没反应，其实容器可能已启动又立刻退出。必须看日志才能知道为什么：

• 先用 docker-compose ps 看各服务状态：是 Up、Exited 还是 Restarting
• 对状态异常的服务，执行 docker-compose logs -f 。重点看最后几行——是连接数据库超时？是找不到配置文件？还是应用启动时抛了 Java Exception 或 Node.js require 错误？
• 如果日志为空或只有“Starting”，说明容器根本没跑起来，问题大概率在前面两步（配置语法或资源依赖）

检查依赖服务是否真就绪，不只是“已启动”

depends_on 只控制容器启动顺序，不保证服务可用。Web 服务连不上刚“启动”的数据库，是高频失败场景：

• 错误表现：web 容器反复重启，日志里全是 “Connection refused” 或 “failed to connect to db:5432”
• 解决方法：给被依赖服务（如 db）加上 healthcheck，并在 web 的 depends_on 中指定 condition: service_healthy
• 验证健康检查是否生效：运行 docker inspect | grep -A 10 Health，看状态是否为 healthy