镜像里已经写了命令名：容器参数拼接的两种协作方式
一、报错很小，机制很清楚
该避坑指南记录的是一个官方镜像的用法坑：这个镜像把可执行文件写在入口点的位置上。如果在运行命令末尾又把命令名补写一遍，容器运行时会把它拼成”命令名加命令名加参数”，于是第一段被当成子命令，后面的参数落进这个子命令，报出未知参数。指南给的写法是省略命令名，只传参数，并且指出同样的拼接道理对命名卷那类参数同样适用。
这个坑的价值不在难度，在于它暴露的事实：镜像不只是文件系统的打包，它同时是一个命令行接口，而接口里有隐式约定。约定写在镜像元数据里，不在调用方的直觉里。团队里几乎每个人都在某个时刻被这类报错卡住一次，卡住的原因都是同一件事——不知道参数是追加还是覆盖。把这一件事讲清楚，比记十条命令有用得多，也是本篇不打算做成入门教程的理由。
二、两种协作方式：追加与整串交给壳
镜像元数据里有两个位置，一个用于放入口点，一个用于放默认命令。它们的行为差别必须按形式分开说。
数组形式的入口点会把默认命令里的内容当作参数追加在后面。也就是说，最终执行的东西是”入口点里的可执行文件，加上默认命令拆出来的每一项”。调用方在命令末尾补参数时，参数追加在这条链的尾部。这就是为什么重复写命令名会直接把语义搞乱：多出来的那一段不是被忽略，而是被当成一个有意义的参数交给程序去解释。
shell 形式则完全不同：整串内容交给一个壳去执行，此时默认命令不再被追加进来当作参数，而是被拼进那串文本里由壳解释。带来的后果是引号与空格的语义由壳决定，数组形式下天然保留的”一项就是一项”边界消失了。
这两种差别不是风格问题，它决定了调用方能不能安全传参。数组形式对含空格与含特殊字符的参数天然安全，因为它不经过解释；shell 形式则把安全责任推给写镜像的人，必须在文本里自己处理引号。一个镜像选了哪种形式，调用方看到的行为就完全不一样，而这个信息在镜像的公开说明里经常不写。
三、三种常见误用
按上面两条机制，能出问题的写法基本落在这三类里。
第一类是重复命令名，也就是该指南点名的那个错误。它高发是因为调用方的直觉来自普通命令行习惯：在那里”程序名写在最前面”是天经地义的，而在这里程序名已经在入口点里了。这类报错还算客气，至少它报了。
第二类是把入口点当脚本用，又指望参数追加。入口点写成一段要做条件判断、要读多个环境变量的脚本，用 shell 形式串起来；这时调用方传的参数不再被追加到某个程序后面，而是按那串文本自己的方式被消化。结果是参数看似传了却没起作用，或者只起了部分作用，且没有任何错误。这一类比第一类危险，因为它静默。
第三类是用环境变量拼参数，导致空格与引号语义丢失。参数的一部分从环境里取出来，拼进命令文本，值里带了空格或者带了注释符，整条命令的解释就变了。凡是”值的内容由外部提供、又要进入命令文本”的路径，都应该按可能含分隔符来设计，而不是假设运维写的值总是干净的。
三类误用有一个共同解法：让错误写法直接失败并说清原因，而不是让它跑起来再出问题。这一点会在第五节变成镜像设计要主动做的事。
四、编排文件里同样的两条语义
同一个”追加还是覆盖”的问题在编排配置里换个样子再来一遍，这也是排查时最容易搞混的地方。
| 位置 | 语义 | 生效方式 | 常见误解 |
|---|---|---|---|
| 镜像里的入口点 | 主执行内容，形式决定参数怎么拼 | 构建时固化 | 以为编排里改一次就变 |
| 镜像里的默认命令 | 数组形式入口点下作为参数被追加 | 构建时固化 | 以为它总是独立执行 |
| 编排里的命令字段 | 覆盖默认命令这一层 | 部署时生效 | 以为它覆盖了入口点 |
| 编排里的入口点字段 | 覆盖入口点这一层 | 部署时生效 | 以为它只追加参数 |
两个字段名字相近、语义一个是”换掉要执行的参数”一个是”换掉执行什么”，混用后果是本地跑通而线上行为不同。判断编排文件里改参数到底怎么生效，只有一个可靠办法：把最终执行的那一条读出来比对，而不是推测拼接过程。
派生镜像与多阶段构建是第二个混淆源。在自己的镜像里基于官方镜像构建时，入口点会被继承下来，也可能被后写的指令改写；一旦改写，原来”不要重复命令名”的约定就不再成立，而使用方看到的还是同一个镜像名。这类变更必须在镜像发布说明里写明，否则每个调用方都要靠报错重新踩一遍。
五、把镜像当成命令行接口来写文档
内部工具镜像最容易欠的不是功能，是接口说明。我们把它固定成一份模板，跟着镜像版本一起走。
- 形式声明：入口点用数组形式还是 shell 形式；默认命令是什么；调用方传进来的参数会被追加还是被覆盖。这一条要写在文档开头，不藏在示例里。
- 示例调用：给两到三个真实用法，一个最常见的、一个带特殊字符参数的、一个只传配置的。示例的作用是让人照抄而不是推理。
- 显式提醒：把”不要重复写命令名”这类反直觉约束单列一行，写清重复写会得到什么现象。人不会读长段落，但会读一行警告。
- 自检模式：镜像内置一个参数，让它打印最终拼出来的执行内容与解析到的配置，然后正常退出。有这个开关，一半的排查工作不需要读文档也不需要猜。
- 报错优先：无法识别的参数、缺失的必填项、只读挂载下要写文件，都主动报错并说明原因。静默降级是接口设计里的负债，早晚要还。
- 卷协作说明：见下一节，单独列。
这份模板的价值在跨团队协作上。接口约定写在文档里，调用方出的问题就能被归为”文档不足”或者”未按文档调用”，而不是每次都在群里靠人回忆。
六、参数与卷的协作，以及排查顺序
参数拼对了不代表跑得对，因为工作目录与可见文件是另一层变量。三点要一起写进接口说明：路径映射之后，参数里写的相对路径以什么为基准——工作目录变了，同一个参数值指到不同位置；只读挂载时，任何写入都会失败，这个失败要报错而不是被吞掉，特别要检查那些”顺手写个临时文件”的代码路径；命名卷在首次挂载时会用镜像里的内容做初始化，已有数据的卷不会被覆盖，所以”改了镜像里的默认配置但线上还是旧配置”这一类现象，往往是数据卷先存在了，而初始化早就不再执行。
排查顺序我们定成三步，按代价从低到高。先看容器起来之后实际执行的那条内容，这是唯一的事实来源；再比对镜像元数据里的两个位置，看差异出在构建还是出在部署；最后回到开发环境，用交互方式把执行入口换成一个能打印参数的壳，把拼接结果打出来复现。这三步走完，绝大多数参数类问题的成因是明确的。反过来，跳过第一步去改代码，通常只是把现象挪了个位置。
团队层面的规则收敛成几条清单：所有内部工具镜像统一入口点风格，尽量用数组形式，非要用 shell 形式要在文档里写明理由；每个镜像必须有自检开关；示例命令作为契约测试纳入流水线，镜像构建后自动跑一遍，示例失败就挡住发布；发布说明里必须写调用形式与是否变更了入口点；派生镜像改了入口点，必须在自己的文档里显式覆盖上游的说法。
在洹拓给客户交付的容器化组件里，我们把”接口约定文档齐全”当成验收项之一。判断标准很具体：调用方不需要读镜像构建内容，只看文档就能写出正确的参数。这一条比镜像本身做得多漂亮都重要——一个隐式约定多的镜像，会在每一个使用它的团队里重新产生一次同类故障。