内插

Compose 文件中的值可以通过变量设置并在运行时进行内插。Compose 文件使用类似于 Bash 的语法 `${VARIABLE}`。支持 `$VARIABLE` 和 `${VARIABLE}` 两种语法。

对于带花括号的表达式，支持以下格式

  • 直接替换
    • ${VAR} -> VAR 的值
  • 默认值
    • ${VAR:-default} -> 如果 VAR 已设置且非空，则使用 VAR 的值，否则使用 default
    • ${VAR-default} -> 如果 VAR 已设置，则使用 VAR 的值，否则使用 default
  • 必需值
    • ${VAR:?error} -> 如果 VAR 已设置且非空，则使用 VAR 的值，否则报错退出
    • ${VAR?error} -> 如果 VAR 已设置，则使用 VAR 的值，否则报错退出
  • 替代值
    • ${VAR:+replacement} -> 如果 VAR 已设置且非空，则使用 replacement，否则为空
    • ${VAR+replacement} -> 如果 VAR 已设置，则使用 replacement，否则为空

内插也可以嵌套

  • ${VARIABLE:-${FOO}}
  • ${VARIABLE?$FOO}
  • ${VARIABLE:-${FOO:-default}}

Compose 不支持其他扩展的 shell 风格特性，例如 ${VARIABLE/foo/bar}。

只要字符串在 $ 符号后构成有效的变量定义（即字母数字名称 [_a-zA-Z][_a-zA-Z0-9]* 或以 ${ 开头的带花括号字符串），Compose 就会对其进行处理。在其他情况下，它将被保留，不会尝试进行内插。

当你的配置需要字面上的美元符号时，可以使用 $$（双美元符号）。这也会阻止 Compose 进行内插，因此 $$ 允许你引用那些不希望被 Compose 处理的环境变量。

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

如果 Compose 无法解析替换的变量且未定义默认值，它会显示警告并将变量替换为空字符串。

由于 Compose 文件中的任何值都可以通过变量替换进行内插，包括复杂元素的紧凑字符串表示法，因此内插是在每个文件合并之前应用的。

内插仅适用于 YAML 值，而不适用于键。对于少数键实际上是用户任意定义的字符串的地方，例如 labels 或 environment，必须使用替代的等号语法才能应用内插。例如

services:
  foo:
    labels:
      "$VAR_NOT_INTERPOLATED_BY_COMPOSE": "BAR"
services:
  foo:
    labels:
      - "$VAR_INTERPOLATED_BY_COMPOSE=BAR"
页面选项