jQuery UI Progressbar在Jenkins Blue Ocean流水线中不显示阶段进度怎么办？

在Jenkins Blue Ocean流水线页面中嵌入自定义前端逻辑时，jQuery UI Progressbar组件偶尔会出现进度条完全不渲染、只显示空白条或者数值无法实时更新的情况。这个问题通常不是组件本身损坏，而是Blue Ocean的前端资源加载顺序、jQuery版本兼容性以及异步数据更新机制共同作用的结果。我们先从根因入手，再给出两步修复方案。

问题定位：为什么Progressbar在Blue Ocean中会失效？

Blue Ocean是Jenkins官方推出的现代化流水线界面，它本身采用React构建，并通过Webpack打包了完整的依赖，包括自己的一份jQuery副本（通常不是你所使用的那个版本）。当你通过<script>标签在页面中引入另一个jQuery和jQuery UI后，全局的$和jQuery对象会被覆盖或冲突。此时调用$('#progress').progressbar()可能会静默失败，控制台可能出现Uncaught TypeError: $(...).progressbar is not a function。

更进一步，Blue Ocean的页面是单页应用，阶段进度信息通过WebSocket或REST API异步推送。即使进度条初始化成功，但依赖定时器或AJAX回调更新数值时，由于闭包捕获了旧的DOM引用或作用域污染，导致更新操作无法作用到正确的元素上。某些版本的jQuery UI在动画队列中也可能因为元素被React重新渲染而丢失状态。

方案一：隔离jQuery并使用noConflict模式

如果你必须继续使用jQuery UI Progressbar，第一步是避免与Blue Ocean的jQuery冲突。方法是在加载自己的jQuery后立即调用noConflict，并将新的jQuery对象保存到一个独立变量中，例如var jq = $.noConflict(true);。然后把所有依赖自己jQuery的代码封装在一个立即执行函数中，以避免全局污染。

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script>
    var jq = jQuery.noConflict(true);
</script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>
<script>
(function($) {
    $(document).ready(function() {
        // 初始化进度条，初始值为0
        $('#pipeline-progress').progressbar({ value: 0 });
    });
})(jq);
</script>

上面的noConflict(true)会将全局的$和jQuery还原为Blue Ocean原本的引用，而你自己加载的jQuery保存在jq变量中。这样jQuery UI插件的注册会安全地挂载到jq对象上，不会干扰Blue Ocean的运行。

第二阶段是解决动态更新问题。Blue Ocean的流水线阶段数据不会自动触发进度条刷新，你需要通过轮询Jenkins Blue Ocean的REST API获取当前阶段索引，然后在回调里调用jq('#pipeline-progress').progressbar('value', percentage)。注意必须使用同一个jq对象，否则插件方法不可用。同时建议将轮询函数放在setInterval中，并在页面卸载时清理。

function fetchStageProgress() {
    const blueOceanUrl = '/blue/rest/organizations/jenkins/pipelines/' + jobName + '/runs/' + runId + '/nodes/';
    fetch(blueOceanUrl, { headers: { 'Accept': 'application/json' } })
        .then(res => res.json())
        .then(data => {
            const stages = data.filter(node => node.type === 'STAGE');
            const completedStages = stages.filter(stage => stage.state === 'FINISHED' || stage.state === 'SUCCESS').length;
            const totalStages = stages.length;
            const percentage = totalStages === 0 ? 0 : Math.round((completedStages / totalStages) * 100);
            jq('#pipeline-progress').progressbar('value', percentage);
            jq('#progress-label').text(percentage + '%');
        })
        .catch(err => console.error('获取进度失败', err));
}
var pollTimer = setInterval(fetchStageProgress, 3000);
window.addEventListener('beforeunload', function() {
    clearInterval(pollTimer);
});

该方案的优点是保留jQuery UI的视觉样式，并且修复思路直观。缺点是仍然需要额外加载整套jQuery UI库，体积较大，且noConflict模式容易在多人协作中产生新的作用域错误。

方案二：使用原生HTML5 progress元素替代

如果项目对进度条样式要求不复杂，推荐直接使用HTML5的<progress>元素。它与jQuery无关，不存在任何脚本冲突，而且浏览器原生支持进度更新。只需在页面中放置一个<progress id="native-progress" max="100" value="0"></progress>，然后通过JavaScript修改其value属性即可。

样式方面可以通过CSS自定义。例如下面的代码可以将原生进度条改造为与Blue Ocean风格协调的扁平化设计：

#native-progress {
    width: 100%;
    height: 18px;
    appearance: none;
    -webkit-appearance: none;
    border: none;
    border-radius: 9px;
    background-color: #e0e0e0;
    overflow: hidden;
}
#native-progress::-webkit-progress-bar {
    background-color: #e0e0e0;
    border-radius: 9px;
}
#native-progress::-webkit-progress-value {
    background: linear-gradient(90deg, #4caf50, #2196f3);
    border-radius: 9px;
    transition: width 0.4s ease;
}
#native-progress::-moz-progress-bar {
    background: linear-gradient(90deg, #4caf50, #2196f3);
    border-radius: 9px;
}

更新进度的逻辑与方案一中的REST轮询几乎一样，只是把jQuery UI的方法替换为直接操作DOM：

function updateNativeProgress() {
    fetch(blueOceanUrl)
        .then(res => res.json())
        .then(data => {
            const stages = data.filter(node => node.type === 'STAGE');
            const completedStages = stages.filter(stage => stage.result === 'SUCCESS' || stage.state === 'FINISHED').length;
            const percentage = stages.length ? Math.round((completedStages / stages.length) * 100) : 0;
            document.getElementById('native-progress').value = percentage;
            document.getElementById('native-progress-label').textContent = percentage + '%';
        });
}
setInterval(updateNativeProgress, 3000);

原生progress的兼容性很好，现代浏览器（包括IE10+）都支持。唯一的限制是伪元素样式无法在部分旧版浏览器中完全自定义，但满足基本进度展示没有问题。更重要的是，它完全避免了与Blue Ocean前端框架的冲突，代码量也少得多。

对比与最终建议

两种方案都能解决阶段进度显示问题。方案一的优势在于如果团队已经高度依赖jQuery UI的组件体系，迁移成本较低；但需要谨慎处理作用域和反复切换上下文。方案二则更加轻量、稳定，推荐新项目使用。在实际操作中，你也可以先用方案二快速恢复进度显示，再逐步替换残留的jQuery UI组件。

另外注意，无论选哪种方案，轮询Blue Ocean REST API时的鉴权问题不能忽视。如果Jenkins开启了CSRF保护，需要在请求头中添加Crumb信息，或者使用Jenkins的API Token。例如在fetch请求中增加headers: { 'Authorization': 'Basic ' + btoa(user + ':' + token) }。具体实现因Jenkins配置而异。

最后，验证修复效果时，建议打开浏览器控制台观察是否有jQuery相关报错，并用慢速网络模拟确认进度条是否会在多个阶段完成后正确累加。如果使用定时轮询，记得在页面不可见时暂停轮询以节省资源，可以使用document.visibilityState检测。

jQuery UI ProgressbarJenkins Blue Ocean阶段进度显示修改时间：2026-09-20 22:19:40