Dockerfile安装Node.js失败：执行node -v提示node not found

常见原因及解决办法 #

1. 包管理器安装的Node.js命令名为nodejs而非node #

很多Debian/Ubuntu系基础镜像中，Node.js的包名是nodejs，默认执行命令是nodejs而非node，直接调用node -v会失败。

解决步骤：
在安装Node.js后添加软链接，将nodejs映射为node：

# 安装Node.js和npm
RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm
# 创建软链接，让系统识别node命令
RUN ln -s /usr/bin/nodejs /usr/bin/node

2. Node.js安装路径未加入全局PATH #

如果通过二进制包解压、nvm等方式安装Node.js，其所在目录可能不在默认PATH中，导致后续RUN命令无法找到node。

二进制包安装场景：

直接将Node.js解压到全局目录（如/usr/local），该目录默认在PATH中：

# 下载并解压Node.js二进制包到/usr/local，自动加入PATH
RUN curl -fsSL https://nodejs.org/dist/v20.10.0/node-v20.10.0-linux-x64.tar.xz | tar -xJ -C /usr/local --strip-components=1

nvm安装场景：

nvm安装的Node.js仅在当前shell会话生效，需将nvm环境配置写入全局profile，确保后续RUN命令能加载：

# 安装nvm并指定Node.js版本
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash \
    && . ~/.nvm/nvm.sh \
    && nvm install 20 \
    && nvm alias default 20 \
    # 将nvm配置写入全局profile，让所有shell会话生效
    && echo "export NVM_DIR=\"$HOME/.nvm\"" >> /etc/profile.d/nvm.sh \
    && echo "[ -s \"$NVM_DIR/nvm.sh\" ] && \. \"$NVM_DIR/nvm.sh\"" >> /etc/profile.d/nvm.sh

# 用bash -c加载profile后执行node版本检查
RUN bash -c 'echo "The version of Node.js is $(node -v)"'

3. Docker分层构建导致环境变量未继承 #

每个RUN指令都是独立的shell环境，若在一个RUN中临时设置PATH，后续RUN不会继承。需用ENV命令设置全局PATH：

# 假设Node.js安装在/opt/node/bin目录
RUN mkdir -p /opt/node && curl -fsSL https://nodejs.org/dist/v20.10.0/node-v20.10.0-linux-x64.tar.xz | tar -xJ -C /opt/node --strip-components=1
# 将Node.js的bin目录加入全局PATH
ENV PATH="/opt/node/bin:$PATH"

# 此时可正常执行node命令
RUN echo "The version of Node.js is $(node -v)"

排查验证步骤 #

• 安装Node.js后，添加RUN which node或RUN ls -la /usr/bin/node，查看node命令的实际路径是否存在
• 添加RUN echo $PATH，确认Node.js所在目录是否在PATH中

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