--build-arg 不能改写 dockerfile 路径，但可通过预声明 arg（如 arg app_src_dir=src）并在 copy、workdir 等指令中引用（如 copy ${app_src_dir}/. /app/），实现构建时动态路径控制，且参数仅限构建期生效、不保留于镜像中。

使用 --build-arg 无法直接“改写 Dockerfile 的构建路径”，但可以动态控制 COPY、ADD 或 WORKDIR 等指令中涉及的路径行为——前提是这些路径在 Dockerfile 中通过构建参数（ARG）定义，并在后续指令中被引用。

确保 ARG 在使用前被正确定义

Docker 构建时，ARG 必须在对应 FROM 之后、实际使用之前声明，且对中间阶段生效范围有限。若想在 COPY 中动态指定源目录或目标路径，需显式声明并赋值：

• ARG APP_SRC_DIR=src —— 声明默认值，便于本地调试
• COPY ${APP_SRC_DIR}/. /app/ —— 引用参数，路径随构建参数变化
• 注意：ARG 不能用于 FROM 行（除非是多阶段构建中的基础镜像名），也不能跨阶段自动继承

配合 COPY/ADD 实现动态源路径切换

当项目结构存在多个可选构建入口（如 backend/、frontend/），可通过构建参数区分：

minimax-mcp-docker版（适配极空间）

MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。

下载

• Dockerfile 中写：ARG SERVICE_PATH=backend，然后 COPY ${SERVICE_PATH}/. /srv/app/
• 构建时指定：docker build --build-arg SERVICE_PATH=frontend -t myapp .
• ⚠️ 注意：宿主机上必须真实存在该路径，Docker 不会创建不存在的源目录；COPY 路径是相对于构建上下文根目录的，不是容器内路径

动态设置 WORKDIR 或安装路径

某些工具链要求安装到特定路径（如 Python 的 site-packages 或 Node.js 的 node_modules 位置），可用 ARG 控制：

• ARG INSTALL_PREFIX=/opt/myapp
• WORKDIR ${INSTALL_PREFIX}
• RUN pip install --prefix ${INSTALL_PREFIX} -r requirements.txt
• 这样就能在不同环境中复用同一 Dockerfile，仅靠参数切换部署布局

避免常见陷阱

构建参数不是环境变量，不会自动保留在最终镜像中（除非显式用 ENV 赋值），也不影响运行时行为：

• --build-arg 传入的值仅在构建期间有效，ARG 指令本身不会出现在最终镜像的层中
• 不要依赖未声明的 ARG：比如写了 COPY ${MY_DIR}/. /app/ 却没提前 ARG MY_DIR，Docker 会当作字面量 ${MY_DIR} 处理，导致路径错误
• 敏感信息（如密钥）不应通过 --build-arg 传递，因其会留在镜像历史中；应改用 --secret 或构建器挂载