env 指令是 dockerfile 中设置环境变量最常用、最可靠的方式，变量在构建时写入镜像层并自动在容器运行时生效；支持单变量与多变量写法，推荐后者以减少层数；允许变量复用、构建阶段展开，但不可存敏感信息。

直接在 Dockerfile 里用 ENV 指令设置环境变量是最常用、最可靠的方式。这些变量会在镜像构建时写入镜像层，并在容器启动后自动生效，无需额外操作或运行时传参。

基础写法：单个与多个变量

ENV 支持两种格式，推荐使用多变量单行写法，更简洁且减少镜像层数：

• 单变量写法（清晰适合少量变量）：
  ENV NODE_ENV production
ENV PORT 3000
• 多变量写法（推荐，一行定义多个）：
  ENV NODE_ENV=production PORT=3000 LOG_LEVEL=warn

注意：等号两侧不能有空格；含空格或特殊字符的值要用双引号包裹，例如：ENV APP_NAME="My App v2"。

变量复用：用已有变量定义新变量

后续 ENV 指令可引用前面定义的变量，提升可维护性：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

• ENV APP_HOME=/app
• ENV PATH=$APP_HOME/bin:$PATH
• WORKDIR $APP_HOME
• COPY . $APP_HOME/

这样修改 APP_HOME 路径时，所有依赖它的地方都会同步更新，避免硬编码出错。

构建阶段可见性与运行时持久性

用 ENV 设置的变量不仅在容器运行时有效，在构建阶段（如 RUN 指令中）也能被展开使用：

• ENV VERSION=1.2.0
• RUN curl -o app.tar.gz https://example.com/app-v$VERSION.tar.gz

这些变量会固化进镜像，无法被外部 --env 覆盖，除非显式在 docker run 中用 -e 重设同名变量（此时运行时值优先级更高）。

常见注意事项

• 变量名建议全大写、下划线分隔（如 DB_HOST），符合 Unix/Linux 习惯
• 不要在 ENV 中写敏感信息（如密码、密钥），应改用 --env-file 或 Secret 管理
• ENV 不支持从文件（如 .env）自动读取 —— 那需要构建参数（ARG + ENV）或 entrypoint 脚本实现
• 若需动态加载 .env 文件内容，属于运行时行为，不属于 ENV 指令职责范围