更新WordPress Docker镜像版本时为何出现`npm: not found`错误？

我之前碰到过这个问题：用Docker部署的WordPress站点，原Dockerfile基于wordpress:6.2.0-php8.1-apache，更新WordPress核心到6.2.2版本后，构建镜像时触发npm: not found错误。

原Dockerfile片段 #

FROM composer:2.5.8 as composer
FROM wordpress:6.2.0-php8.1-apache

# ...

RUN apt-get update \
    && curl -sL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y unzip nodejs jq \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

RUN npm install && npm run build

报错信息 #

> [stage-1 9/9] RUN npm install && npm run build:
0.224 /bin/sh: 1: npm: not found
------
Dockerfile:36
--------------------
  34 |     
  35 |     # Compile SCSS
  36 | >>> RUN npm install && npm run build
  37 |     
--------------------

问题原因 #

WordPress官方镜像在6.2.1及后续版本中调整了基础系统的环境配置，导致通过nodesource源安装的Node.js和npm没有被正确加入系统PATH，或者安装过程中存在静默兼容问题，使得后续命令找不到npm。

解决方案 #

方案1：强制配置PATH环境变量

在安装nodejs的RUN指令末尾，添加PATH配置或软链接，确保npm能被全局调用：

RUN apt-get update \
    && curl -sL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y unzip nodejs jq \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    # 确保npm路径被加入环境变量
    && ENV PATH="/usr/bin:${PATH}"

或者用软链接方式：

RUN apt-get update \
    && curl -sL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y unzip nodejs jq \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && ln -s /usr/bin/npm /usr/local/bin/npm \
    && ln -s /usr/bin/node /usr/local/bin/node

方案2：改用多阶段构建分离Node.js环境

更稳妥的方式是把前端构建步骤放到单独的Node.js镜像阶段，避免和WordPress镜像的环境冲突：

FROM composer:2.5.8 as composer
# 单独用Node.js镜像做前端构建
FROM node:20-bullseye as frontend-builder

# 复制项目文件到构建阶段
COPY . /app
WORKDIR /app
# 执行依赖安装和构建
RUN npm install && npm run build

# 回到WordPress镜像
FROM wordpress:6.2.2-php8.1-apache

# 从构建阶段复制编译好的静态文件到WordPress主题目录（根据实际路径调整）
COPY --from=frontend-builder /app/dist /var/www/html/wp-content/themes/your-theme/dist

# 只安装WordPress需要的工具，不再装Node.js
RUN apt-get update \
    && apt-get install -y unzip jq \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# 其他WordPress配置...

这种方式不仅解决了环境冲突问题，还能减小最终镜像的体积，符合Docker最佳实践。

验证方法 #

修改Dockerfile后，可以临时添加RUN npm --version到安装Node.js的指令后面，确认npm能正常输出版本号，再继续后续构建步骤。

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