docker构建阶段安全注入版本号和环境参数需用arg指令配合--build-arg，明确区分构建期与运行期：显式声明arg并设默认值、避免传敏感信息、通过label/文件/env精准落地、多阶段需重声明arg。
在 Docker 构建阶段安全注入版本号和环境参数，核心是用好 ARG 指令配合 --build-arg，同时明确区分“构建期”与“运行期”的职责边界。关键不在于传得快，而在于传得准、留得少、用得清。
正确声明 ARG 参数并设默认值
所有需动态注入的变量，必须在 Dockerfile 中显式声明，并优先设置合理默认值，避免因漏传导致构建失败：
-
ARG APP_VERSION=1.0.0—— 语义化版本默认值，便于本地快速验证 -
ARG BUILD_ENV=dev—— 环境标识默认为开发，CI 流水线再覆盖 -
ARG COMMIT_SHA—— 无默认值，表示该参数必须由外部提供（如 CI 变量），否则构建中断 - 参数名统一用大写加下划线，符合 Docker 社区惯例，也方便脚本解析
构建时安全传参，避开敏感信息陷阱
版本号和环境名本身不敏感，但传参方式决定是否引入风险：
- 命令行直接传参：适用于非敏感字段，例如
docker build --build-arg APP_VERSION=2.4.0 --build-arg BUILD_ENV=prod -t myapp:2.4.0 . - 从 CI/CD 变量透传：GitHub Actions 中用
--build-arg COMMIT_SHA=${{ github.sha }}，GitLab CI 中用--build-arg CI_COMMIT_TAG=$CI_COMMIT_TAG，天然隔离本地环境 - 绝不通过
ARG传密钥、token、数据库密码——这些值会保留在镜像历史层中，docker history或docker inspect即可查看。真要处理敏感信息，请改用docker buildx build --secret或挂载文件方式
精准落地：让版本和环境既可用又可控
ARG 值只存在于构建过程，若需在容器启动后读取，必须主动转出；若仅构建时使用，则不应污染镜像：
- 写入镜像元数据供追踪：
LABEL app.version=${APP_VERSION} build.env=${BUILD_ENV} - 写入文件供应用读取（推荐）：
RUN echo "${APP_VERSION}" > /app/VERSION && echo "${BUILD_ENV}" > /app/ENV - 导出为运行时环境变量（谨慎）：
ENV APP_VERSION=${APP_VERSION} ENVIRONMENT=${BUILD_ENV}—— 这会固化进镜像，后续无法被docker run -e完全绕过，适合真正需要启动即生效的配置 - 不要混用：比如声明
ARG NODE_ENV却没写ENV NODE_ENV=$NODE_ENV，容器里就根本看不到这个变量
多阶段构建中注意作用域隔离
每个 FROM 开启新构建阶段，ARG 不自动继承，必须按需重声明：
- 若基础镜像需动态选择（如
FROM node:${NODE_VERSION}-alpine），ARG NODE_VERSION必须写在FROM之前 - 构建器阶段和最终运行阶段都要用到
APP_VERSION？那就得在两个阶段开头分别写一次ARG APP_VERSION - 重复声明同名 ARG 不报错，但后声明的会覆盖前一个，影响其后的指令，建议命名清晰、阶段内只声明一次
