Compose 文件版本从 3.x 升到 3.8，表面是改一个 version 字段，实际涉及解析器、引擎版本和运行时行为三处变化。下面按升级顺序整理常见卡点，以及每一步怎么确认。
先确认引擎和 Compose 工具版本
Compose 文件版本 3.8 要求 Docker Engine 至少为 19.03.0，且 Compose 命令行工具不低于 1.25.0。升级前先执行 docker-compose version 与 docker version --format '{{.Server.Version}}'，确认两个版本都在门槛之上。若引擎版本过低，即使配置文件通过语法检查，运行时也可能在创建指定资源时失败。不要只关注文件语法，还要在真实引擎上用同一份配置启动应用，才能确认兼容性。
这步的意义是把“配置文件语法没问题”和“环境能跑起来”分开。很多升级失败发生在引擎版本不够又无法升级的场景下，比如内网环境只允许特定版本镜像，此时可以先停留在低版本，而不是强行改 version。需要结合环境确认。
改完配置先做静态验证
修改 version 字段后，执行 docker-compose config --quiet 是最快的语法验证手段。如果返回非零退出码，说明存在当前 Compose 解析器无法识别的键或值。许多常见的升级问题，如误将 2.x 格式的 volume 挂载语法沿用，在 config 阶段不会报错，而是会被忽略，导致容器运行时目录为空或出现权限错误。因此，除了确认无错误输出，还需要人工检查 config 输出的实际内容，尤其是 volumes、ports 和 environment 部分。不要嫌麻烦，这一步能省掉后续调试时间。
补充：docker-compose config --quiet 通过不代表配置语义正确。建议把完整输出保存为文件，人工检查 volumes、ports、environment 的取值。比如挂载路径是否被解析成绝对路径，端口映射是否多了 0.0.0.0 前缀。这一步能提前暴露大部分升级引入的隐性变化。
环境变量转义最容易踩
在 Compose 3.8 中，所有需要保留到容器再求值的 $ 符号，必须写成 $$。如果沿用旧版单 $ 写法，docker-compose config 会将其解释为宿主环境变量，未定义时替换为空字符串。一个常见现象是，容器内读取到配置中的路径变成 ':/app' 或出现参数缺失。升级时，建议全文检索所有 '$' 字符，逐条确认其意图。可用 docker-compose config 打印解析结果，观察 environment 中是否出现了意外空值，这是验证转义是否正确的最直接方式。
这个空值现象在 entrypoint 里用了 ${VERSION} 这类变量时尤其典型，如果本意是让容器在运行时解析，升级后没改成 $$，宿主机又没有同名变量，就会变成空。建议在升级前列一个变量清单，标明每个变量的解析时机，再结合 config 输出验证。
depends_on 与 build/image 的坑需要单独确认
在 Compose 3.8 中，depends_on 仍然只支持服务名序列，不支持 condition 关键字。若从 2.x 迁移或旧配置文件里残留了 condition: service_healthy，docker-compose up 会直接报错并提示 attribute not supported。正确做法是在应用入口脚本中自行探测依赖服务健康状态，或者使用 healthcheck 配合外部依赖等待工具。升级时，还要注意 depends_on 的顺序并不严格保证完全可用，只能决定启动顺序，不能保证服务就绪。不要依赖这个字段做状态同步。
检查 depends_on 的时候，也顺手看一眼 config 解析出来的服务列表，确认被忽略的键有没有影响启动顺序。如果没有 condition，那么依赖服务可能还没就绪，主服务就起来了，日志里会出现连接被拒或超时，这并不一定是配置错误，而是依赖处理方式没跟上。
当一个服务同时写 build 和 image 时，image 会被当作构建产物的仓库和标签。如果只写 build 不写 image，Compose 会根据项目名和服务名自动生成默认镜像名，不同版本拼接规则不同。升级后镜像名可能变化，导致在集群里拉不到镜像。建议在所有带 build 的服务上显式写 image，并执行 docker-compose build 和 docker-compose push 验证名称是否符合预期。
升级后检查弃用警告
改完配置和启动成功后，还要看 docker-compose config 输出里的弃用警告。不同小版本对同一字段判性可能不同，有的在 3.x 里仍能工作，但警告会提示规划迁移。比较常见的是 3.0 阶段标记实验性的属性，在 3.8 中变成标准写法。建议把 config 输出保存为文件，搜索 deprecated 和 warning 字样，逐条核对。如果暂时无法替换，记录风险边界，留到后续窗口处理，别忽略。
最后提醒一点：升级前用 git 或其他版本控制保存原文件，回滚时直接恢复 version 字段和改动行。升级是否成功，最终要写在测试环境用同一份配置跑起来，观察日志和资源创建情况。不要只依赖语法检查。