PrimeFaces 12.0.0文件上传报错：文件名含':'禁止，如何解决？

错误原因 #

当用户上传的文件名包含冒号（:）时，PrimeFaces依赖的Apache Commons IO工具类会判定这是NTFS交替数据流（ADS）的分隔符，出于安全限制直接抛出非法参数异常，触发验证阶段错误。

解决方案 #

1. 前端提前拦截非法文件名 #

在用户选择文件时就阻止上传带冒号的文件，给p:fileUpload添加前端验证逻辑：

<p:fileUpload ... onchange="validateFileName(this)" />

<script>
function validateFileName(fileInput) {
    const files = fileInput.files;
    for (let i = 0; i < files.length; i++) {
        const fileName = files[i].name;
        if (fileName.includes(':')) {
            alert('文件名不能包含冒号，请修改后重新上传');
            fileInput.value = ''; // 清空已选文件
            return false;
        }
    }
    return true;
}
</script>

2. 后端主动清理非法字符 #

如果需要兼容用户上传带冒号的文件，可在后端处理上传前替换文件名中的冒号为合法字符（如下划线）：

// 获取上传文件对象
UploadedFile uploadedFile = ...;
String originalFileName = uploadedFile.getFileName();
// 将冒号替换为下划线，保留原文件名其他内容
String sanitizedFileName = originalFileName.replace(':', '_');
// 使用清理后的文件名执行后续存储等操作

3. 扩展PrimeFaces的文件名验证逻辑 #

若不想修改前端或业务代码，可以自定义文件名验证逻辑，覆盖PrimeFaces默认的检查规则。比如创建自定义工具类替换默认的FileUploadUtils，或通过CDI扩展拦截验证流程，跳过冒号检查（注意：此方式可能带来安全风险，需结合业务场景评估）。

4. 升级PrimeFaces版本 #

PrimeFaces后续版本（如13及以上）可能调整了文件名验证逻辑，支持配置是否禁用ADS分隔符检查。可尝试升级到最新稳定版，同时做好业务兼容性测试。

内容的提问来源于stack exchange，提问作者Mahmoud Saleh