可在Dockerfile中用LABEL指令或docker build --label参数为镜像添加结构化元数据，推荐优先使用OCI标准键名（如org.opencontainers.image.*），支持构建时动态注入变量，且命令行--label会合并并覆盖同名键值。
可以在构建镜像时通过 Dockerfile 中的 LABEL 指令，或在 docker build 命令中用 --label 参数，为镜像添加结构化元数据（如项目名称、版本、作者、用途等），这些信息不会影响运行行为，但便于团队协作、CI/CD 跟踪和镜像治理。
在 Dockerfile 中定义 Labels
这是最常用、最推荐的方式，让元数据与构建逻辑保持一致，也方便版本控制。
- 在
Dockerfile的任意位置（通常放在FROM后、CMD前）添加一行或多行LABEL指令 - 语法格式为：
LABEL key1="value1" key2="value2"，支持空格、引号、换行（用反斜杠续行） - 示例：
LABEL org.opencontainers.image.title="user-service" \
org.opencontainers.image.description="REST API for user management" \
org.opencontainers.image.version="1.2.0" \
org.opencontainers.image.authors="dev-team@example.com" \
org.opencontainers.image.licenses="MIT" \
com.example.project-id="PROJ-456" \
com.example.git-commit="a1b2c3d"
注意：Open Containers Initiative（OCI）定义了一套推荐的 标准 Label 键名（以 org.opencontainers.image.* 开头），建议优先使用，提升兼容性（如被 Harbor、Notary、Cosign 等工具识别）。
构建时动态添加或覆盖 Labels
适用于需要根据环境注入变量（如 Git 分支、CI 构建号）的场景，可结合 shell 变量或 CI 系统环境变量使用。
- 用
docker build --label参数追加或覆盖Dockerfile中已定义的 Label - 多个
--label可重复使用，也可一次写多个键值对（用空格分隔） - 示例（在 CI 脚本中）：
docker build \ --label "org.opencontainers.image.revision=$GIT_COMMIT" \ --label "org.opencontainers.image.source=$GIT_REPO_URL" \ --label "com.example.build-date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ -t myapp:latest .
⚠️ 注意：命令行传入的 --label 会**合并**而非完全覆盖 Dockerfile 中的同名 Label；若键名相同，命令行值会生效（即后定义者优先）。
查看和验证 Labels 是否生效
构建完成后，可用以下命令检查镜像是否携带预期元数据：
-
docker inspect <image-name-or-id> | jq '.[0].Config.Labels'</image-name-or-id>（需安装jq，输出清晰 JSON） - 或直接查看：
docker inspect <image-name> --format='{{json .Config.Labels}}'</image-name> - 也可用
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Labels}}"查看简略标签摘要（部分旧版 Docker 不显示完整内容）
如果返回为空对象（{}），说明未正确设置；若只显示部分键，检查是否拼写错误、引号不匹配或构建时漏传参数。
实际使用中的注意事项
- Label 值应避免敏感信息（如密钥、内部 IP、账号密码），它随镜像分发，可能被任意用户 inspect 到
- 键名建议统一风格（如全小写+连字符），避免空格和特殊字符；OCI 标准键名优先于自定义键名
- Label 不参与层缓存计算，增删改不影响构建速度，但过度冗余（如嵌入大段日志）可能略微增大镜像配置大小
- 多阶段构建中，只有最终阶段的 Labels 会保留在输出镜像里；中间阶段的 Labels 不会继承
