为何docker run传入的环境变量在Dockerfile的CMD中无法解析？

问题现象 #

执行docker run --rm -it -e APP_PORT=80 -p 8080:80 my_container <image-id>启动容器时，Dockerfile中以下两种CMD写法无法解析环境变量APP_PORT，容器日志报错：

错误：'$APP_PORT' 不是有效的端口号

CMD ['gunicorn', "-b", "0.0.0.0:${APP_PORT}", "main:app"]  # 无法生效！
CMD ['gunicorn', "-b", "0.0.0.0:$APP_PORT", "main:app"]    # 无法生效！

而另外两种写法可以正常解析APP_PORT：

CMD ["sh", "-c", "echo 0.0.0.0:$APP_PORT"]                 # 可以生效！
CMD gunicorn -b 0.0.0.0:$APP_PORT main:app                 # 可以生效！

核心原因：Docker CMD的两种执行模式 #

Docker的CMD指令有两种执行模式，环境变量解析逻辑完全不同：

• Exec模式（数组形式）
  当CMD使用数组格式（如CMD ["command", "arg1", "arg2"]）时，Docker会直接调用该命令的二进制文件，不会通过shell进程执行。这意味着数组中的所有参数都会被当作字面量传递给命令，$APP_PORT或${APP_PORT}不会被解析为环境变量，而是作为字符串直接传给gunicorn，导致gunicorn将其识别为无效端口号。

• Shell模式
  当CMD使用无引号的字符串格式（如CMD command arg1 arg2），或者显式通过sh -c调用时，Docker会自动启动一个shell进程（默认是/bin/sh）来执行命令。shell进程会负责解析命令中的环境变量，将$APP_PORT替换为实际的环境变量值（即80），因此可以正常生效。

解决方法 #

如果需要在CMD中使用环境变量，二选一即可：

1. 使用Shell模式的CMD写法：

   CMD gunicorn -b 0.0.0.0:$APP_PORT main:app
   

2. 显式调用shell执行命令（适合需要复杂命令逻辑的场景）：

   CMD ["sh", "-c", "gunicorn -b 0.0.0.0:$APP_PORT main:app"]
   

内容的提问来源于stack exchange，提问作者m19v