Dockerfile使用ARG传NPM_TOKEN构建时仍报环境变量替换失败错误

你当前写法有两个核心问题：

• 执行docker build时，宿主机直接定义的NPM_TOKEN=mySecretToken属于宿主机shell的本地环境变量，不会自动透传到Docker构建流程中，必须显式指定传参才能被构建流程读取。
• Dockerfile中声明的ARG是Docker构建层面的元变量，不会自动注入到RUN指令启动的子shell环境里，yarn读取.npmrc中的${NPM_TOKEN}占位符时找不到对应值，就会触发环境变量替换失败的报错。

绝对不要把NPM_TOKEN通过ENV指令写入镜像，否则token会永久留在镜像层中，任何拿到镜像的人都可以读取到这个认证密钥，存在严重安全风险。

1. 调整构建命令 #

构建时必须通过--build-arg参数显式传入构建变量：

docker build --build-arg NPM_TOKEN=mySecretToken .

2. 单阶段Dockerfile安全写法 #

核心逻辑是仅在执行yarn install的单个RUN步骤中临时注入变量，安装完成后立刻删除.npmrc配置，避免密钥残留在镜像层：

# 声明构建参数
ARG NPM_TOKEN

# 移动提前准备好的npm配置文件
RUN mv .npmrc.docker .npmrc
# 执行安装时，仅对当前shell进程临时注入NPM_TOKEN变量，变量不会残留到后续镜像层
RUN NPM_TOKEN=${NPM_TOKEN} yarn install --frozen-lockfile
# 安装完成立刻删除带认证信息的配置文件
RUN rm -f .npmrc

# 后续拷贝源码、构建、启动配置等指令正常编写即可

3. 零泄露风险的多阶段构建方案 #

如果要彻底避免token被打包进最终镜像，推荐使用多阶段构建，把依赖安装和最终镜像构建拆成两个完全隔离的阶段，密钥只在第一阶段存在，根本不会进入最终运行镜像：

# 第一阶段：仅用于安装依赖，此阶段会接触NPM_TOKEN
FROM node:18-alpine AS dependency
WORKDIR /app
ARG NPM_TOKEN
COPY package.json yarn.lock .npmrc.docker ./
RUN mv .npmrc.docker .npmrc \
    && NPM_TOKEN=${NPM_TOKEN} yarn install --frozen-lockfile \
    && rm -f .npmrc

# 第二阶段：构建最终运行镜像，此阶段完全不接触NPM_TOKEN
FROM node:18-alpine AS runner
WORKDIR /app
# 仅从第一阶段拷贝安装好的依赖文件，不会携带任何认证信息
COPY --from=dependency /app/node_modules ./node_modules
COPY package.json yarn.lock ./
COPY . .
# 正常配置启动命令即可
CMD ["yarn", "start"]

内容的提问来源于stack exchange，提问作者Dave