Nuxt + Spring Boot 容器化排雷：Docker Compose 常见坑点与自检清单

前段时间在跑本地的 Nuxt + Spring Boot 项目时，在 docker-compose.yml 的编写上结结实实地栽了个跟头。

原本以为把前端和后端的 Dockerfile 写好，再用 Compose 编排一下就能一键 docker-compose up -d 快乐启动了。结果一敲回车，要么是服务启动直接 Crash，要么是前端 Nuxt 疯狂报 500，死活连不上后端的 Spring Boot 接口。

经过和各种诡异报错的一番“搏斗”，我总结出了在编写 Docker Compose 文件时最容易踩的几个坑，以及一套高效的排错流程。

💥 我遇到的核心问题与踩坑点
🛠️ 解决问题的实操流程
✅ 黄金准则：Docker Compose 编写 Self-Check 清单
结语

💥 我遇到的核心问题与踩坑点

在排查了半天后，我发现导致项目起不来的罪魁祸首集中在以下几个方面：

1. YAML 缩进与语法格式（无声的杀手）

YAML 对缩进极其敏感。我在复制粘贴环境变量配置时，多敲了一个空格，或者把数组格式（-）对齐错了，导致整个 environment 节点解析失败。这种语法层面的错误，有时候单看肉眼极难察觉。

2. 容器间的网络隔离与 `localhost` 陷阱

这是全栈容器化最容易犯的错。在 Nuxt (SSR) 端发起请求时，我习惯性地把后端 API 地址写成了 http://localhost:8080。
但问题是，在 Docker 内部，每个容器都有自己的 localhost！Nuxt 容器里的 localhost 指的是前端容器自己，根本找不到 Spring Boot。必须使用 Compose 中定义的服务名（Service Name）作为域名来进行互相访问。

3. 环境变量覆盖失败

Spring Boot 项目强依赖外部配置。我尝试在 Compose 文件中注入特定的环境变量（比如之前提到的通过 SPRING_APPLICATION_JSON 强制修改内部路由），但因为格式书写错误，或者没有使用引号包裹复杂的 JSON 字符串，导致 Spring Boot 根本没有读到这些配置，直接连了错误的数据库或注册中心。

4. 启动顺序依赖 (`depends_on`)

Nuxt 容器启动速度极快，而 Spring Boot 启动需要几秒钟甚至更长。Nuxt 启动后立刻去请求后端接口，结果后端还没就绪，直接导致前端 SSR 渲染报错崩溃。

🛠️ 解决问题的实操流程

遇到容器起不来的情况，不要慌，按照以下步骤层层剥茧：

语法校验先走一步：
在终端运行 docker-compose config。这个命令不会启动容器，而是会把你当前的 YAML 文件解析一遍。如果有任何缩进错误或语法问题，它会直接报错并指出行号。
看日志，看日志，看日志：
使用 docker-compose logs -f <服务名> 实时查看崩溃容器的日志。如果是 Spring Boot 报错，看是不是数据库连不上；如果是 Nuxt 报错，看具体的网络请求堆栈。
进入容器内部抓包/测试：
如果怀疑是网络问题，可以直接进入容器内部：docker exec -it <容器ID> /bin/sh。然后在里面用 curl 命令尝试 ping 或访问其他容器的服务名，看网络是否打通。
修复并重建：
修改完 docker-compose.yml 后，一定要加上 --build 参数重新启动：docker-compose up -d --build，确保最新的配置生效。

✅ 黄金准则：Docker Compose 编写 Self-Check 清单

为了避免以后再犯低级错误，我给自己定下了一套写完 Compose 文件后的 Self-Check（自检）清单。每次 up 之前，在脑子里过一遍：

[ ] 端口冲突检查： 宿主机映射的端口（ports: "8080:80" 的左边）是否已经被本地的其他进程占用？
[ ] 网络连通性： 容器之间互相调用时，URL 是否使用了正确的服务名（Service Name）而不是 localhost？
[ ] 路径挂载映射： volumes 挂载的本地宿主机路径是否正确？尤其是在 WSL 环境下，路径的写法是否有误？
[ ] 依赖顺序： 是否配置了 depends_on？（注意：depends_on 只能保证容器启动顺序，不能保证服务完全就绪，生产环境建议配合健康检查 healthcheck 使用）。
[ ] 敏感信息隔离： 密码、Token 等机密信息是否直接硬编码在 YAML 里了？（最佳实践是提取到 .env 文件中，通过 ${VAR_NAME} 引用）。
[ ] 引号问题： 环境变量中的复杂字符串（尤其是包含冒号、大括号的 JSON 串）是否用单引号或双引号正确包裹了？