Docker Compose 报 env_file.0 must be a string：旧版本不支持可选环境文件

执行 docker compose up -d 时，容器还没有启动，配置校验就停在：

services.web.env_file.0 must be a string

服务名也可能是 sandbox。如果对应配置使用了 path 和 required，核对实际调用的 Compose 版本：

env_file:
  - path: ./envs/web.env
    required: false
  - ./.env

这是服务配置中的一个片段。第一个条目是映射，第二个条目是文件路径字符串。env_file.0 指列表的第一个元素；错误中的“必须是字符串”针对这个 YAML 条目，不是在要求把环境文件里的数字全部加引号。

本文处理旧解析器不支持可选环境文件的情况。required 从 Docker Compose 2.24.0 开始支持。如果文件还用了 format: raw，该功能需要 2.30.0 或更新版本，不能只满足前一个下限。应用的其他配置也可能有更高要求，这两个版本号不是整套应用的最低部署承诺。

先确认部署进程调用了哪套 Compose

在发生错误的机器、用户和执行环境中检查版本。如果原命令带连字符，也一并检查：

docker compose version
docker-compose version

某个命令不存在，只说明那种入口未安装。两种写法可能指向不同程序；终端里更新了插件，部署脚本仍运行另一份旧程序，错误就会保留。不要只看 Docker Engine 的版本，也不要仅凭命令中有无连字符判断版本。

如果部署由 CI、面板或脚本执行，应查看它实际运行的命令与版本。把宿主机插件升级，并不能证明运行在另一个执行环境中的工具也更新了。

随后校验原项目的配置。以下文件名是示例，要替换成实际 Compose 文件：

docker compose -f ./docker-compose.yaml config -q

原来使用多个 -f、--env-file、项目目录参数或特定工作目录时，校验也要沿用。config -q 不输出展开后的完整配置，可减少环境变量中的凭据进入日志的机会。普通 config 可能打印这些值，不要把完整输出贴到公开工单。

检查报错服务的 env_file 第一个元素。如果确实是上述映射形式，且实际 Compose 版本低于 2.24.0，就符合本文的版本不兼容场景。如果版本已支持该功能，继续检查实际入口、读取的文件及 YAML 结构；不要把每个 must be a string 都归为同一个原因。

更新解析配置的工具，保留原有可选语义

required: false 的作用是：文件不存在时，Compose 跳过这个条目。required 默认为 true。配置作者可能有意把部分环境文件设为可选，再让所有部署都读取末尾的 .env。

优先安装当前受支持、满足应用要求的 Compose 版本，保留原配置。对于已经安装 Docker Engine 和 CLI、并配置好 Docker 官方软件仓库的 Ubuntu 或 Debian，可以更新 Compose 插件：

sudo apt-get update
sudo apt-get install docker-compose-plugin
docker compose version

这组命令不适用于尚未配置对应仓库的系统，也不用于更新手动放置的独立程序。Docker Desktop 用户通过 Desktop 的更新方式处理；手动安装用户应按原安装方式更新，并重新确认部署入口的版本。

升级前记录当前工具版本与安装来源，保存项目配置和环境文件。更新插件后先做配置校验，再安排应用原有的部署流程。若需要回退工具，应通过原安装渠道恢复已记录的版本，并搭配它能解析的配置；不要退回旧工具后继续使用新语法。应用已经发生数据迁移时，回退插件本身不能撤销迁移。

修改 YAML 顶层的 version: "3.8" 不会给已安装的 Compose 增加功能。当前 Compose 将该字段视为兼容性信息；功能支持取决于实际程序。

临时改成路径列表，会失去“文件可选”

如果暂时无法升级，并且这些文件都确实存在、可读，且配置没有依赖其他映射选项，可以把上面的片段改成旧式路径列表：

env_file:
  - ./envs/web.env
  - ./.env

但这不等价于原配置：./envs/web.env 现在也必须存在。把可选条目改成字符串后，如果它原本就不存在，报错可能从类型错误变成找不到文件。

不要为了让校验通过就随意删除文件条目，或创建空文件冒充完整配置。只有已经确认该文件在这套部署中本来就不提供任何设置，才可以在保留备份的前提下省略它。若文件存在，其中的变量可能覆盖前面文件的值；更改条目顺序也可能改变最终配置。

这里的相对路径以 Compose 文件所在目录为基准。多个环境文件从上到下读取，同名变量采用后读入的值；服务的 environment 还会覆盖 env_file 的值。只改语法时保留路径、顺序及其他环境配置，避免顺手改变应用参数。用了 format: raw 的配置也不能直接套用这个转换，因为普通环境文件的值解析方式不同。

临时修改前另存原文件并记录改动。升级工具后可以恢复原来的映射写法，再次校验，重新获得缺少可选文件时跳过的行为。

校验通过与应用恢复分开确认

更新实际入口后，用与部署一致的参数重新执行：

docker compose -f ./docker-compose.yaml config -q
docker compose -f ./docker-compose.yaml config --services

第一条成功退出且不再出现类型错误，说明这一配置解析障碍已经消除；第二条用来核对读到的服务清单是否属于目标项目。两步都不会创建服务，也不能证明数据库连接、凭据或应用健康状态正常。

随后按该应用的部署说明更新服务，保留原来的项目名、数据挂载和环境参数。若仅消除了类型错误，却出现缺少环境文件或必填变量的提示，应根据新错误补齐真实配置，不要继续围绕旧报错重装工具。服务启动后再核对运行状态与实际业务入口；这次解析问题不需要删除数据卷，也不需要重建数据库。