Jenkins构建React项目时npm install报错，怎么排查？

别走弯路了，这问题我踩过，基本就是网络问题，但不是你想象的那么简单。

ENETUNREACH 这个错误很明确：网络不可达，通常是服务器出不去公网，或者 DNS 解析失败，或者代理没配对。

先确认 Jenkins 所在服务器能不能直接连 registry.npmjs.org：

在 Jenkins 服务器上执行：

ping registry.npmjs.org

curl -v https://registry.npmjs.org/

如果 ping 不通，或者 curl 卡在 connect 阶段，说明网络层就断了。

常见原因有三类：

1. 服务器在内网，出公网要走代理
检查服务器有没有配置全局代理（比如 /etc/profile 里的 http_proxy、https_proxy），或者有没有写进 /etc/environment
Jenkins 运行用户（通常是 jenkins）有没有继承这些环境变量？
很多时候 Jenkins 是以服务方式启动的，不会加载 /etc/profile，得去改 systemd service 文件（比如 /etc/systemd/system/jenkins.service）里加 Environment=HTTPS_PROXY=xxx

2. DNS 解析失败
nslookup registry.npmjs.org 看能不能解析出 IP，如果解析不了，试试改 /etc/resolv.conf 加个 8.8.8.8 或 114.114.114.114

3. 防火墙/安全组拦截了出站 443 端口
如果你在云上（阿里云、腾讯云、AWS），检查安全组规则，出方向是不是允许了 HTTPS（443）

临时验证方法：在 Jenkinsfile 里加一步打印网络环境：

stage('Debug Network') {

    steps {

        sh 'env | grep -i proxy'

        sh 'cat /etc/resolv.conf'

        sh 'curl -v https://registry.npmjs.org/ 2>&1 | head -20'

    }

}

跑完看输出，哪一步卡住、哪条 proxy 变量是空的，基本就能定位了。

如果实在搞不定公网，就换内网 npm 私服（比如 Nexus、Verdaccio），把 .npmrc 放到项目根目录：

registry=http://your-npm-proxy:4873

别在 Jenkins 里反复试 npm config set registry，除非你确认是源地址问题，否则大概率白折腾。

最后提醒：别用 --legacy-peer-deps 了，现在 React 18 + axios 这种组合早不缺 peer deps，加它反而可能掩盖真实问题，先解决网络，再考虑要不要加这个参数。

这个错误大概率是网络问题，效率最高的排查方法是这样。先确认Jenkins服务器是不是能访问外网，直接在Jenkins服务器上执行 curl https://registry.npmjs.org，如果连不通，那就是网络策略的问题。

很多公司生产环境服务器都是内网隔离的，你得找运维确认下防火墙规则。如果确实不能直接访问外网npm源，建议换淘宝镜像，速度也快。在Jenkins的全局配置里加上这行：npm config set registry https://registry.npmmirror.com，或者直接改项目根目录下的.npmrc文件。

另外你用的是--legacy-peer-deps参数，这个没问题，但建议把npm版本固定一下。我遇到过类似情况，最后发现Jenkins用的Node.js版本太老了，建议升到16以上。完整的解决方案是：

// Jenkinsfile片段

pipeline {

    agent any

    stages {

        stage('Setup') {

            steps {

                sh 'node -v && npm -v'

                sh 'npm config set registry https://registry.npmmirror.com'

            }

        }

        stage('Install') {

            steps {

                sh 'npm install --legacy-peer-deps'

            }

        }

    }

}

最后提醒一句，记得检查Jenkins的工作空间权限，有时候权限不够也会导致安装失败。按这个思路排查，基本都能解决。