Docker部署Node应用启动时无法读取.env文件问题排查

一、Dockerfile中RUN npm install返回exit code 127的原因与解决 #

原因 #

nvm的初始化逻辑通常写入用户的shell配置文件（如~/.bashrc或~/.profile），而Docker的RUN指令默认使用非交互式的sh shell，不会自动加载这些配置文件，导致npm命令无法被找到，从而抛出exit code 127（命令未找到）错误。而手动进入容器时，默认使用交互式bash shell，会自动加载nvm的配置，因此npm可以正常执行。

解决方案 #

方案1：在RUN指令中手动加载nvm配置

直接在执行npm install前加载nvm的初始化脚本：

RUN source ~/.nvm/nvm.sh && npm install

方案2：在基础镜像中全局配置nvm环境变量

制作基础镜像时，将nvm的路径加入系统环境变量，避免每次RUN都要手动加载：

# 安装nvm后，添加以下配置
ENV NODE_VERSION=18.10.0
RUN nvm install $NODE_VERSION \
    && nvm alias default $NODE_VERSION \
    && nvm use default
# 将Node和npm的路径加入全局PATH
ENV PATH="/root/.nvm/versions/node/v${NODE_VERSION}/bin:${PATH}"

后续的RUN npm install即可直接使用，无需额外加载配置。

方案3：直接使用Node的完整路径

如果不确定环境变量配置是否生效，可直接指定npm的绝对路径：

RUN ~/.nvm/versions/node/v18.10.0/bin/npm install

二、容器启动后Node无法读取.env文件导致端口显示undefined的原因与解决 #

核心关联 #

这个问题本质是Dockerfile中npm install执行失败，导致依赖包（如dotenv）未安装，Node无法读取.env文件中的配置。手动执行npm install后，依赖被补全，因此端口恢复正常。解决上述第一个问题后，此问题通常会自动消失，但也可以补充以下配置确保稳定：

额外保障措施 #

1. 启动脚本中加载nvm配置

容器启动脚本默认也可能使用sh shell，需手动加载nvm配置以保证Node环境正常：

#!/bin/bash
# 加载nvm配置
source ~/.nvm/nvm.sh
# 启动服务
node ./your-entry-file.js

2. 确保工作目录与文件路径正确

在Dockerfile中用WORKDIR指定服务端代码的工作目录，并确保.env文件被复制到该目录：

WORKDIR /app/server
# 复制服务端代码
COPY ./server/dist .
# 复制.env文件
COPY ./server/.env .

3. 确认代码中dotenv的正确调用

检查服务端入口文件是否在最开始加载dotenv：

// CommonJS
require('dotenv').config();
// ES模块
import dotenv from 'dotenv';
dotenv.config();

// 确保PORT读取逻辑正确
const port = process.env.PORT || 3000;
console.log(`服务器运行在端口 ${port}`);

内容的提问来源于stack exchange，提问作者Santiago Sotelo Docío