★ FEATURED ARTICLE 如果你在 Jenkins 里尝试装过中文语言包大概率见过这样一条红字Plugin “Chinese (Simplified) Language Pack / 中文语言包“ was not installed: Invalid filename returned by https://...第一次看到这个报错的人基本都懵了网络明明是通的插件列表也能刷出来为什么偏偏这个包装不上有人不死心连续点“安装”结果每点一次失败一次系统日志里全是同一句话。今天这篇就把这个报错从头到尾拆干净包括它背后的下载机制、排查思路、三种从快到稳的解决办法再加上一份常见变体和避坑速查表。刚接触 Jenkins 的新手可以直接照做被这个问题反复折磨过的运维也能从里面找到一些排查灵感。1. 先把报错拆开看Invalid filename returned by 到底是什么意思1.1 一个再常见不过的失败现场这个报错的完整形态通常长这样Plugin “Chinese (Simplified) Language Pack / 中文语言包“ was not installed: Invalid filename returned by https://updates.jenkins.io/download/plugins/localization-zh-cn/1.3.1/localization-zh-cn.hpi“Invalid filename returned by”后面跟的是一个完整的插件下载链接。很多人会误以为这是“插件不存在”或者“版本找不到”实际完全不是这么回事。这个错误的核心信息是Jenkins 去那个链接下载插件文件的时候拿到的文件名不合法不是它期望的.hpi或.jpi格式于是整个安装过程被直接中断。也就是说Jenkins 不是下载不到东西而是下载到了一个“它不认识的东西”。打个比方你去餐厅点了一份红烧肉服务员确实端了一盘东西过来但打开盖子一看是个空盘子里面还放了张纸条写着“菜单”。这时候你肯定会拒绝收货对吧Jenkins 也是这么个态度我要的是.hpi插件包你返回给我的却不是那我就认栽报错。1.2 下载链路上到底哪一步出了差错要真正理解这个报错得先看 Jenkins 从“点击安装”到“插件出现”之间经历了什么。整个过程大致是四步Jenkins 读取更新中心配置文件update-center.json拿到插件列表和每个插件的元数据。你勾选插件并点击安装后Jenkins 根据元数据里的下载地址向远程服务器发起 HTTP 请求。服务器返回插件文件localization-zh-cn.hpiJenkins 把它保存到本地$JENKINS_HOME/plugins目录。Jenkins 校验文件名和文件完整性确认无误后解压安装。问题往往就出在第三步和第四步之间。正常情况下服务器响应头里会带有Content-Disposition: attachment; filenamelocalization-zh-cn.hpi这样的信息Jenkins 用这个来决定把文件保存成什么名字。但如果这条请求经过某些网络中间层时被拦截比如企业网关、安全设备、云防火墙之类返回的可能是一个 HTML 错误页面、一段 JSON 提示文本甚至是一个登录跳转页面。这个时候 Jenkins 拿到的是一个乱七八糟的文件名比如error.html、login.jsp或者干脆没有合法的.hpi后缀它就会抛出Invalid filename returned by URL。为什么报错给人的感觉是“网络是通的”因为update-center.json这个文件能正常下载插件列表能正常加载页面也能正常刷出来。真正出问题的是后续的插件文件下载环节。很多人在这个坑里卡半天就是因为没意识到“连接通”和“下载链路健康”是两回事。还有一种常见情况是更新中心地址被换成了某个不完整的镜像站镜像站只同步了 JSON 文件没有同步插件文件目录或者同步了一半。Jenkins 照样能拿到元数据但下载时镜像返回的是 404 页面最终也会被识别成“无效文件名”。2. 排查三连看日志、试下载、定位是哪一环在捣乱2.1 别急着重试先抓一条完整日志很多人遇到这个报错第一反应是再点一次安装这其实是效率最低的做法。正确的第一步是去把日志翻出来看看报错连带的那个完整 URL 到底是什么。日志入口有两个地方系统管理 → 系统日志 → 所有 Jenkins 日志或者直接看$JENKINS_HOME/logs/目录下的日志文件在 Linux 环境里$JENKINS_HOME一般是/var/lib/jenkins。不确定的话可以在系统管理 → 系统设置里找到“主目录”这个字段。日志里搜关键词Invalid filename returned by能看到完整的异常栈。重点看两件事第一报错里出现的 URL 是官方更新中心域名还是某个镜像域名第二URL 末尾的插件版本号和当前 Jenkins 版本是否匹配。这些信息直接决定后面用哪个方案处理。grep -n Invalid filename returned by /var/lib/jenkins/logs/*.log有些情况下日志里还会同时看到Connection timed out、Premature end of Content-Length delimited message body等网络类异常这些和Invalid filename的成因不同处理方式也不一样。2.2 用 curl 复现一次下载看响应头拿到报错里的 URL 之后不要只在浏览器里打开看一眼因为浏览器默认会渲染页面HTML 页面看起来也像正常页面。更靠谱的做法是用命令行直接请求这个地址观察 HTTP 响应头。假设报错里的 URL 是https://updates.jenkins.io/download/plugins/localization-zh-cn/latest/localization-zh-cn.hpi执行curl -sIL https://updates.jenkins.io/download/plugins/localization-zh-cn/latest/localization-zh-cn.hpi参数说明-I表示只拿响应头-L表示跟随重定向。看几个关键字段HTTP/1.1 200 OK请求成功。Content-Type: application/java-archive或application/zip返回的是插件包正常。Content-Disposition: attachment; filenamelocalization-zh-cn.hpi文件名正确正常。Content-Type: text/html或Content-Type: application/json返回的是页面异常。只要发现Content-Type是text/html基本就能确定是中间层拦截了下载请求返回了一个页面给 JenkinsJenkins 不认识这个“文件名”所以安装失败。如果是 404那就是镜像站没有同步这个插件目录属于源的问题。如果是 403那就是网关或安全策略直接拒绝了.hpi请求。2.3 结果就三类对号入座根据上面两步的观察这个报错基本可以归类成三种情况观察结果问题类型优先处理方式响应头是text/html或文件名不是.hpi下载链路被网络中间层干扰换镜像源或离线安装响应头是 404更新中心镜像同步不完整更换为官方源或其他镜像下载正常但安装仍失败本地缓存损坏或权限问题清缓存后重试这三种情况我全都遇到过处理难度从低到高大概是缓存问题最简单换源稍麻烦一点离线安装基本能解决前两种。下面一个个说。3. 三种解法换源、离线包、清理缓存3.1 方案A把更新中心换成国内镜像源如果你的网络环境访问官方更新中心不太稳定替换更新中心地址是最直接的在线安装方案。操作路径进入 系统管理 → 插件管理 → 高级设置。找到“更新站点”配置项默认地址是https://updates.jenkins.io/update-center.json。把这个地址替换成国内开源镜像站的更新中心地址。我这边常用的是某个高校开源软件镜像站地址格式类似https://mirrors.某高校.org/jenkins/updates/update-center.json你可以换成自己实际用的镜像站。点击“立即检查”或“提交”让 Jenkins 重新拉取一次插件元数据。回到“可选插件”页面重新搜中文语言包并安装。为什么换镜像能解决一部分问题因为镜像站在同步update-center.json的时候会顺带把里面的插件下载路径改写成本镜像站的地址。这样你后续下载的插件文件全部走镜像站的下载链路绕过了官方源的下载域名也就绕开了那个返回无效文件名的中间环节。需要注意的是换源之后插件管理页里显示的源地址变了但“可选插件”里还是能搜到中文语言包。如果搜不到先点“立即检查”强制刷新一次元数据。3.2 方案B手动上传 .hpi 离线安装最稳换源后如果还是报同样错误或者你不想在插件管理页上反复折腾直接走离线安装。这个方法最适合那种“在线下载怎么都不对但浏览器访问网络又没问题”的环境。步骤拆解打开浏览器进入镜像站的插件下载目录。对应中文化插件的目录名是localization-zh-cn。选择一个和当前 Jenkins 版本兼容的版本下载localization-zh-cn.hpi文件。回到 Jenkins系统管理 → 插件管理 → 高级设置。找到“上传插件”区域点击“选择文件”选中下载好的.hpi文件点击“上传”。上传完成后Jenkins 会提示插件已安装部分版本需要重启才能生效。注意一个细节下载插件文件时如果直接在浏览器里点击下载有些镜像站会给文件重命名比如变成localization-zh-cn.hpi (1)或者因为浏览器默认安全策略问题保存下来的是一个 HTML 文件而不是真正的插件包。上传之前最好确认一下文件类型。Linux 环境可以用file命令快速验证file localization-zh-cn.hpi如果输出是Zip archive data说明文件正常。如果输出是HTML document说明你保存到的是个网页赶紧删掉重新下载。更省心的方式是用命令行下载直接指定输出文件名wget -O localization-zh-cn.hpi https://镜像站地址/localization-zh-cn.hpi3.3 方案C清理插件缓存后重试如果你之前已经尝试过好几次在线安装每次都以失败告终那本地plugins目录里大概率残留了半截下载文件。这些残留文件有时候会干扰后续安装导致你反复报同样的错误。处理方式先彻底停掉 Jenkins 服务或者用 系统管理 → 安全重启 的方式重启。进入$JENKINS_HOME/plugins目录。查找文件名里带有tmp、part、以及localization-zh-cn字样的文件。把localization-zh-cn.hpi.part这类临时文件删掉。重启 Jenkins重新执行在线安装。ls -lh /var/lib/jenkins/plugins/ | grep -i localization这个方法不能解决所有问题但如果你的报错是“第一次安装失败第二次又失败之后每次必然失败”大概率就是残留文件在作怪。清干净之后原来的报错可能直接就消失了。4. 一次真实排障从报错到界面变中文的完整过程4.1 现场信息还原某开发团队的内网环境里跑着一个 Jenkins版本是某 2.4xx。同事在“可选插件”里搜到“Chinese (Simplified) Language Pack”点击安装等了几分钟页面上方出现一条红色错误提示Plugin “Chinese (Simplified) Language Pack / 中文语言包“ was not installed: Invalid filename returned by https://updates.jenkins.io/download/plugins/localization-zh-cn/latest/localization-zh-cn.hpi系统日志里留下了更具体的异常信息java.io.IOException: Invalid filename returned by https://updates.jenkins.io/download/plugins/localization-zh-cn/latest/localization-zh-cn.hpi at hudson.model.UpdateCenter$DownloadJob.run(UpdateCenter.java:...)同事问我怎么办我的排查路径是这样的。4.2 从报错到界面中文化的完整过程第一步先看报错里的 URL域名是updates.jenkins.io说明还没换过更新中心源。这个环境是内网访问外网要走统一出口中间有一层安全设备怀疑下载请求被这层设备返回了拦截提示页。第二步用 curl 模拟下载观察响应头curl -sIL https://updates.jenkins.io/download/plugins/localization-zh-cn/latest/localization-zh-cn.hpi响应结果里Content-Type是text/htmlContent-Disposition也没有出现。这就证实了我的判断Jenkins 下载到的不是插件包而是一个页面。第三步准备换国内镜像源。把更新中心地址改成了某高校镜像站的update-center.json地址点击“立即检查”后插件列表可以正常刷新。但重新安装时又失败了这次报错里的 URL 变成了镜像站地址响应内容依然是text/html。说明这台机器的出口流量对所有外域名都走同一道安全网关镜像域名也被拦了。第四步走离线安装。直接在浏览器里访问同一个镜像站的插件目录页面手动下载localization-zh-cn.hpi上传到 Jenkins 的“上传插件”区域。上传完成后 Jenkins 提示安装成功并建议重启。第五步安全重启 Jenkins。重启完成后进入 系统管理 → 外观Appearance→ 语言把语言切换为“中文简体”整个界面立刻变成中文。整个排障过程大约十几分钟真正卡时间的不是操作本身而是“第一次没看响应头差点又在那反复重试”。4.3 几个当时最关键的判断依据回头复盘有几个信息点对快速定位起了决定性作用报错里的 URL 域名是哪个决定了要不要先换源。响应头的Content-Type是text/html还是application/java-archive直接区分了“链路拦截”和“下载正常”。浏览器能打开页面不代表 Jenkins 能下载成功因为 Jenkins 要的是文件浏览器要的是渲染后的页面两者关心的东西完全不同。如果你的环境和这个案例类似我建议直接跳过在线安装的反复重试第一个动作就去看响应头第二个动作就直接准备离线包。这能省掉至少半小时的无效操作。5. 这份报错的常见变体和避坑速查5.1 报错变体速查表Invalid filename returned by这个报错在 Jenkins 的插件安装场景里有一大群亲戚表现形式略有不同根因大同小异。我把常见变体整理成一张表报错内容可能原因首选处理Invalid filename returned by https://...hpi下载请求被中间层拦截返回非插件文件换镜像源或离线安装Failed to download from https://...网络连接超时或链路不通检查网络出口再决定换源还是重试Checksum mismatch下载文件被篡改或镜像同步不完整清缓存换版本重新下载Plugin is not installed: ...且日志里无网络异常本地文件残留或插件依赖未安装清理plugins目录残留文件上传.hpi后提示版本不兼容插件要求的最低 Jenkins 版本高于当前版本下载旧版插件包很多变体表面看着不一样比如Checksum mismatch经常被误认为是网络安全问题实际上大多数情况是下载时文件被网关做了内容替换或者镜像站同步到一半就把文件暴露出来了。处理方式仍然是“清缓存重下”或“离线安装”。5.2 离线上传时最容易踩的四个坑离线安装虽然是压舱石方案但操作细节上有几个坑不留意还是会浪费时间。第一个坑是文件名不对。从浏览器下载插件保存下来的文件可能是localization-zh-cn.hpi (1)这种文件上传时 Jenkins 一般能识别但部分旧版本会把括号当非法字符直接拒绝。上传前把文件名改成localization-zh-cn.hpi这样的纯格式。第二个坑是下载到假的hpi文件。镜像站如果要求登录你在未登录状态点击下载拿到的可能是登录页的 HTML。上传后 Jenkins 会报“文件不是有效插件包”到这一步再去查文件类型就多绕了一圈。所以下载完立刻用file命令验证。第三个坑是插件依赖没装。中文化插件不是孤立的它可能依赖前端资源库、公共语言库等基础插件。离线上传主插件时Jenkins 会提示缺少某个依赖。解决办法是在插件详情页把依赖列表一起下载下来逐个离线上传。第四个坑是上传后没重启。很多插件安装后只提示“安装完成”但功能没生效。别急着点进“已安装插件”页面确认直接在系统管理页面做一次安全重启最省心。5.3 一点经验小结我自己在排这种问题的时候已经不太愿意在“在线安装”上死磕了。凡是遇到Invalid filename returned by这种带下载环节的报错第一反应就是去日志里把 URL 捞出来第二反应是用 curl 看响应头然后就根据结果决定是换源还是手动下载。在线安装按钮诚然方便但前提是下载链路足够干净一旦链路被中间层污染离线安装往往是代价最小、成功率最高的那条路。这个方法不只适用于中文语言包。其他 Jenkins 插件只要出现同样的Invalid filename returned by报错处理思路完全一致找到报错 URL、下载正确的.hpi文件、离线上传、重启。这套流程吃透之后你在任何一台网络环境“不太好伺候”的 Jenkins 上排插件问题心里都会更有底。
阅读完成 · 觉得有帮助？
