Docker容器执行npm run production报ENOTDIR错误排查求助

• 核心报错ENOTDIR: not a directory和前置的utf-8-validatepeer依赖警告没有直接关系，该警告只是可选性能依赖缺失，属于非致命提示，不会中断npm执行流程。
• 90%以上的同类报错由环境版本严重不兼容导致：从日志看容器内运行的是2017年发布的Node v6.9.5 + npm v3.10.10，该版本对@types/xxx这类scoped包的staging临时目录处理存在已知bug，完全不兼容当前主流前端依赖（包括日志中出现的ws@8.2.3、新版@types/node）的安装逻辑，安装过程中无法正确生成临时目录结构就会触发该错误。
• 剩余小概率诱因包括：node_modules目录残留旧版本安装的损坏文件、宿主机与容器挂载卷的文件权限映射冲突、npm本地缓存损坏。

• 先执行docker exec -t [你的容器ID/名称] node -v && npm -v确认容器内实际运行的Node、npm版本，和项目package.json中engines字段要求的最低版本做比对，优先确认版本差问题。
• 若版本符合项目要求，进入容器项目路径执行ls -la /var/www/localhost/htdocs/node_modules/.staging/，查看报错提及的@types/node-16824c86路径实际是文件、不存在还是权限异常，确认是否为残留文件或权限问题。
• 若项目目录是宿主机挂载到容器的卷，先在宿主机侧检查对应目录下是否有其他Node版本生成的node_modules残留，跨架构/跨版本的依赖残留也会触发安装异常。

优先方案：对齐Node/npm到兼容版本 #

直接替换容器内的老旧Node版本为LTS长期支持版（推荐v18或v20），是长期解决该问题的最优方式：

• 若镜像通过自定义Dockerfile构建，直接替换基础镜像为官方Node LTS版本，示例：

# 替换原有基于老旧系统源带node6的基础镜像
FROM node:20-alpine
# 保留原有镜像构建逻辑：安装系统依赖、拷贝项目代码、配置服务启动项等

重新构建镜像后再执行生产构建命令即可。

• 若为临时测试不需要重建镜像，可进入容器手动升级版本：

# 进入容器交互终端
docker exec -it [容器ID] sh
# 安装Node版本管理工具升级到LTS版
npm install -g n
n lts
# 刷新环境变量后验证版本
hash -r
node -v # 正常输出v20.x对应版本
npm -v # 正常输出9.x以上版本

缓存与残留清理方案 #

若版本确认符合要求，全量清理损坏的依赖和缓存后重装：

# 进入容器交互终端
docker exec -it [容器ID] sh
cd /var/www/localhost/htdocs
# 强制删除旧依赖、锁文件和npm缓存
rm -rf node_modules package-lock.json
npm cache clean --force
# 重新安装依赖后执行构建
npm install
npm run production

注意：如果是宿主机挂载目录，需要先在宿主机侧删除对应目录下的node_modules文件夹，避免跨版本残留文件干扰安装流程。

权限问题修复 #

清理缓存后仍报错的，检查目录执行权限：

# 容器内执行，将项目目录权限分配给实际运行服务的用户（比如常见的www-data、node用户，按自己容器配置调整）
chown -R www-data:www-data /var/www/localhost/htdocs

避免用root用户执行npm install，否则生成的目录权限和后续运行服务的业务用户不匹配，也会触发目录读写类错误。

可选警告处理 #

核心报错解决后，若要消除ws的peer依赖警告，安装对应可选依赖即可：

npm install utf-8-validate@^5.0.2 --save-optional

该依赖为ws模块的二进制性能加速包，不安装也不会影响功能正常运行。

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