dockerfile 无法定义镜像标签，需通过 --build-arg 注入 version 并配合 label 和 ci/cd 实现版本统一；推荐用 git describe 自动生成可追溯标签；按语义化主版本、环境、架构分层打标；禁止覆盖已发布 tag，确保不可变性。
直接在 Dockerfile 里无法定义或管理镜像标签（tag）——标签是构建后由 docker build -t 指定的，Dockerfile 本身只负责描述如何构建镜像。规范化管理标签与版本号，关键在于把版本信息“带进来”、统一注入、并和 CI/CD 流程对齐。
用构建参数（--build-arg）传入版本号
这是最常用也最灵活的方式。Dockerfile 中用 ARG 声明变量，CI 脚本在构建时通过 --build-arg 注入真实值：
- Dockerfile 开头声明：ARG VERSION=v0.0.0
- 可在构建阶段使用该变量，比如设置 LABEL：LABEL version=$VERSION
- CI 中执行：docker build --build-arg VERSION=v1.2.3 -t myapp:v1.2.3 .
这样既能保证镜像内嵌版本元数据，又让外部 tag 和内部 LABEL 保持一致，便于审计和排查。
结合 Git 提交信息自动生成标签
避免人工维护版本号出错，推荐从代码仓库自动提取上下文：
- 用
git describe --tags --always --dirty获取最近 tag + 提交偏移（如 v1.2.0-3-gabc123-dirty） - CI 脚本中捕获该值，作为
--build-arg或直接用于-t参数 - 示例命令：TAG=$(git describe --tags --always); docker build -t myapp:$TAG .
这种方式天然具备可追溯性，每个镜像都能精准对应到某次代码提交，适合开发和预发环境。
按环境与架构分层打标，不堆砌冗余信息
一个镜像可打多个 tag，但要避免“一镜多标”变成混乱源头。推荐分层策略：
- 主版本 tag：v1.2.3（语义化，生产唯一可信标识）
- 环境补充 tag：v1.2.3-prod、v1.2.3-staging（仅用于部署策略，不替代主版本）
- 架构标识 tag：v1.2.3-amd64、v1.2.3-arm64（由多平台构建流程生成，非手动拼接）
不要把所有信息塞进一个 tag，比如 v1.2.3-prod-amd64-20260813 —— 时间戳和架构应由构建系统自动处理，而非硬编码在 Dockerfile 或脚本里。
禁止覆盖已发布 tag，用版本递进代替重推
CI 流水线必须校验：若目标 tag（如 v1.2.3）已在 registry 存在，则跳过推送或报错退出：
- 先尝试
docker pull $IMAGE:$TAG，成功即说明已存在 - 存在时拒绝构建或强制使用新版本号（如 v1.2.4）
- 修复 bug 应发布 v1.2.4，而不是重推 v1.2.3
这是保障镜像不可变性和部署可重现性的底线规则，必须固化在 CI 脚本中，不能依赖人工约定。
