构建参数是什么
把外部值传进构建过程，供构建指令按值分支或填入内容。它适合传版本号、镜像变体、环境标识这类构建期的可变信息。需要清楚两点：参数要在构建描述里声明才生效，值会留在镜像的构建历史里，因此不能用来传凭据。
基本信息
| 传递方式 | 构建命令里指定键值对，可多次传入 |
|---|---|
| 生效前提 | 构建描述里先用声明指令声明该参数 |
| 作用范围 | 仅构建期，不会写入运行期配置 |
| 默认值 | 可在声明时给默认值，未传入时使用默认值 |
| 缓存影响 | 参数值参与缓存键计算，改动会触发相关层重建 |
典型使用场景
- 版本号注入：把发布版本写进镜像内的版本文件或标签
- 基础镜像变体切换：同一描述按参数选择不同的基础镜像版本
- 依赖源切换：内网环境传入内部镜像源地址，外网环境用默认源
- 条件构建：按参数决定是否执行某些可选步骤
- 流水线集成：把流水线变量传给构建过程，实现构建与发布的衔接
常用示例
常用示例
docker build --build-arg APP_VERSION=1.2.3 --build-arg BASE=node:22-alpine -t app/web:1.2.3 .
docker build --build-arg APP_VERSION=$CI_COMMIT_TAG -t app/web:$CI_COMMIT_TAG .
docker build --build-arg NPM_REGISTRY=https://registry.internal.example.com -t app/web:1.2.3 .
docker image inspect app/web:1.2.3 --format '{{json .Config.Env}}' # 核对写入的环境变量构建参数与环境变量对照
| 对比项 | 构建参数 | 环境变量 |
|---|---|---|
| 生效阶段 | 仅构建期 | 构建期与运行期 |
| 运行期可见 | 不可见 | 进程内可读 |
| 写入镜像配置 | 不写入运行配置 | 写入运行配置 |
| 覆盖方式 | 构建时传入，需要重新构建 | 运行时注入同名变量 |
| 适合内容 | 版本号、镜像变体、源地址 | 运行模式、时区、编码 |
使用时注意
- 参数必须在构建描述里声明，写错键名字母或漏声明都会静默不生效
- 含空格或特殊字符的值要用引号包住，避免被 shell 提前拆分
- 参数值进入镜像历史，凭据类内容要改用专用的构建期凭据机制
- 参数变更会影响缓存，频繁变化的参数不要放在早期指令里
- 需要运行期可见的值，应在构建描述里转成环境变量，或改为运行时注入
构建参数的值会保留在镜像的构建历史中，任何拿到镜像的人都能查到。令牌、密码必须用构建期凭据机制，不要图方便用参数传递。
传了构建描述里没声明的参数不会报错，只是不起作用，最多给出提示。参数不生效时先核对声明与拼写，再怀疑参数传递本身。