Jenkins Pipeline配置NodeJS插件后执行npm命令报错exit code243

退出码243是Docker版Jenkins搭配NodeJS插件的典型兼容故障，和Jenkinsfile里的tools声明语法无关。

• 最新版Jenkins官方Docker镜像基于Debian 12(Bookworm)构建，NodeJS插件自动拉取的部分Node预编译包依赖旧版libssl1.1/libcrypto.so.1.1组件，镜像默认没有预装，npm启动时直接静默崩溃，没有任何业务报错就退出，才会出现日志里只打印了执行命令就直接失败的现象。
• 次要触发原因：全局工具配置中选择的Node版本过高（18+以上版本），插件自动安装过程中受容器内jenkins用户权限限制，node/npm二进制文件没有可执行权限，运行时直接被系统终止返回非0退出码。

1. 先定位具体故障点
   执行以下命令进入运行中的Jenkins容器：
   docker exec -it <你的jenkins容器名称> /bin/bash
   切到NodeJS插件的默认安装路径：
   cd /var/jenkins_home/tools/jenkins.plugins.nodejs.tools.NodeJSInstallation/node/bin/
   直接执行./npm -v，如果输出缺少libssl.so.1.1类依赖报错，就是依赖缺失问题；如果提示Permission denied，就是权限问题。

2. 依赖缺失问题修复
   在容器内执行命令安装兼容依赖：

apt update
apt install -y ca-certificates curl gnupg
# 手动添加bullseye源安装libssl1.1
echo "deb http://deb.debian.org/debian bullseye main" >> /etc/apt/sources.list
apt update
apt install -y libssl1.1

执行完重新跑流水线即可。如果不想改官方镜像，也可以直接基于官方Jenkins镜像写自定义Dockerfile，把上述依赖预装进去，避免每次容器重建都要手动装。

3. 配置校验

• 进入Jenkins后台「全局工具配置」页面，找到NodeJS配置项，确认配置的工具名称和Jenkinsfile中tools块声明的node完全一致，大小写敏感。
• 用插件自动安装Node时，优先选择16.x/18.x LTS版本，不要选20.x以上的最新版本，高版本目前在Docker环境下和插件的兼容问题较多。
• 取消NodeJS配置里「自动安装全局npm包」的勾选，这类附加操作很容易触发目录权限问题。

4. 兼容兜底方案
   如果插件的环境变量注入逻辑始终异常，可以直接在pipeline里手动追加PATH，跳过插件的注入逻辑，示例配置如下：

pipeline {
  agent any
  environment {
    NODE_HOME = tool 'node'
    PATH = "${NODE_HOME}/bin:${env.PATH}"
  }
  stages {
    stage('Clone') {
      steps {
        git branch: 'develop',
            credentialsId: 'gitea-jenkins',
            url: 'http://x.x.x.x:3000/TestRepo'
      }
    }
    stage('Install') {
      steps {
        dir('frontend') {
          sh 'npm config ls'
        }
      }
    }
  }
}

• Docker部署的Jenkins不建议依赖插件自动安装编译类工具，直接在自定义镜像中预装对应版本的Node、npm、maven等工具，稳定性远高于插件自动安装，不会出现依赖缺失、权限不足这类偶发故障。
• 遇到sh步骤无明确报错直接返回非0退出码的情况，优先进容器手动执行对应命令排查，90%以上的这类问题都是容器环境本身的问题，和pipeline语法、插件逻辑无关。

内容的提问来源于stack exchange，提问作者Ivan Vlaho Vlašić