Docker Compose 环境变量报 contains true, which is an invalid type

Compose 在创建容器前就拒绝配置，错误指向某个环境变量：

services.app.environment.FEATURE_ENABLED contains true, which is an invalid type, it should be a string, number, or a null

对应配置通常写了未加引号的 true 或 false。在会拒绝这种类型的 Compose 版本中，给 environment 映射里的值加上引号，让它成为字符串，就能修正这一项类型错误。

这类报错在旧版 Python Docker Compose 1.29.2 中有明确案例。不能据此认定所有新版本都会报同样的错：当前 Compose 规范仍建议给这类环境变量值加引号，而实现对布尔值的接受与转换可能不同。本文适用于已经看到上述类型错误、且错误路径确实落在 environment 下的情况。

改的是值的类型，不是功能开关

下面是容易触发错误的写法，变量名为示例：

environment:
  FEATURE_ENABLED: true

YAML 解析器会把这里的 true 当成布尔值。若 Compose 的环境变量校验不接受布尔类型，容器尚未启动，配置就会被拒绝。改为：

environment:
  FEATURE_ENABLED: "true"

引号限定的是 YAML 类型，不会成为这个环境变量值的一部分。应用拿到的仍是文本 true。如果本来要关闭功能，就保留原意，写成 "false"，不要为了消除报错直接换成 true。

示例中的 FEATURE_ENABLED 需要替换成应用实际支持的变量名。应用是否把 true、false、yes、no 或 1、0 解释为开关，由应用自己的配置规则决定。Compose 能接受字符串，并不保证应用认识任意一种拼写。

只修改 environment，保留其他配置的类型

已有服务通常只需修改报错的值，保留镜像、挂载、网络和其他环境变量。下面展示一个完整的最小服务结构，镜像地址是占位值，应替换成已验证且有权限使用的测试镜像：

services:
  app:
    image: registry.example.com/team/app:tested
    environment:
      FEATURE_ENABLED: "true"
      FEATURE_VERBOSE: "false"

不要把整份 YAML 中的所有布尔值批量加引号。Compose 中其他字段可能本来就要求布尔类型；本次修正针对 services.<服务名>.environment.<变量名>。

如果使用列表形式，整个 KEY=value 条目就是字符串，可以写成：

environment:
  - FEATURE_ENABLED=true
  - FEATURE_VERBOSE=false

同一服务的 environment 应选择映射或列表中的一种结构，不要混写。已有映射时，直接给值加引号最容易审查，无需为了两个变量重排整个配置。

对应用要求的 yes、no 也可以显式保留成字符串，避免不同 YAML 解析器的隐式类型规则造成差异。不要把它们擅自改为 true、false；类型修正不应改变应用接收到的文本。

用同一套 Compose 参数检查修改

先保存配置版本，再用实际部署所用的 Compose 程序检查。下面是 V2 插件命令；如果当前报错来自旧的 docker-compose，应使用同一个程序和相同参数核验，不能拿另一个版本的校验结果代替它：

docker compose -f compose.yaml config --quiet

config --quiet 只校验配置，不输出完整内容。它通过后，再在本地查看展开结果中的目标变量：

docker compose -f compose.yaml config

有覆盖文件时，保留原来的多个 -f 及其顺序；原命令带有环境文件、项目目录等参数时，也要保持一致。否则基础文件虽然修好了，另一个覆盖文件仍可能把值写回错误的类型。

完整配置可能含密码、令牌或其他敏感环境变量，检查时不要直接贴到公开日志。只核对目标变量的类型和最终值，并确认其他配置没有意外变化。若配置由脚本或模板生成，修正生成端输出，避免下一次生成又丢失引号。

把值改成空值也可能避开原来的布尔类型错误，但会改变环境变量的含义：没有明确值的变量需要从外部解析，解析不到时会从容器环境中移除。不要用这种方式代替本来明确的 "false"。

配置通过后，再确认应用真正读到了它

配置校验通过只说明这项错误消失了。应用还可能因为变量名已废弃、值的格式不支持或其他配置问题而失败。应在测试环境确认启动日志、健康状态和实际功能行为，不能把“容器创建成功”直接当成开关生效。

已有容器需要采用更新后的环境配置时，单纯 restart 不会更新环境变量。确认变更范围后，可以通过原部署流程重新执行对应服务的 up，例如：

docker compose -f compose.yaml up -d app

把 app 换成实际服务名。up 可能创建或重建容器，也可能启动相关依赖；正式环境执行前应保留原配置、镜像引用和必要数据备份，并安排允许重启服务的时间。无需为了一个值的类型错误删除数据卷。

如果此时出现新的报错，应按新的错误处理。环境变量类型校验与容器重建失败是两个阶段，加引号不能保证同时修复后者。

需要回退时，恢复上一个已知可用的配置和镜像，再走原部署流程；不要恢复那个本就无法通过校验的裸布尔值。配置回退也不会撤销应用已经写入的数据，因此不能把删除容器或数据卷当作回退步骤。