我在一个信创适配项目里接手过这样的需求业务方要求把原来的单文件上传改成文件夹上传而且必须在国产化浏览器里完整保留用户本地文件夹的路径结构。听起来不算复杂可真正落地时才发现HTML5 的文件夹上传能力在不同国产终端上的表现差异非常大尤其是“路径”这一环稍不注意就会整个消失。用户在本机明明选的是data/2024/quarter/财务.xlsx传到系统里却只剩一个孤零零的财务.xlsx归档时没法按原目录结构还原业务人员当场就急了目录结构都没了还怎么入库这篇文章就围绕“信创环境下 HTML5 如何适配国产化浏览器保留文件夹上传路径”展开把我在这类项目里踩过的坑、查过的源码、最后落地的方案完整梳理一遍。适合正在做信创改造、需要处理批量资料入库、知识库迁移、电子文件归档等场景的开发者参考尤其是前端、全栈和负责终端适配的运维同学。1. 需求背后为什么“文件夹路径”会成为信创适配的硬指标1.1 业务场景到底要什么文件夹上传在传统 Web 系统里一直是个“能做但做得不好”的功能。普通 OA 系统里传几个附件丢文件名无所谓但档案管理、项目资料库、税务申报材料、信创迁移时的存量文件导入都对目录结构有硬性要求。比如某档案系统迁移用户手里是几百个文件夹套嵌的本地目录每个招商项目的合同、批复、扫描件都在对应子目录下上线时希望一键把整个项目目录传上去系统里还保持一模一样的层级。业务方描述需求时往往就一句话“我选的什么目录传上去就什么目录。”但真拆开看这里面包含三层诉求第一层是前端选择文件夹时不丢失层级信息第二层是后端能根据层级信息重建目录结构第三层是用户在系统里再次看到时能按同样的路径找到文件。三层里任何一层断了这个需求就不完整。1.2 浏览器为什么不肯把完整路径给你不少人第一次做文件夹上传第一反应是“拿到文件绝对路径不就行了吗”。实际浏览器出于安全考虑几乎不可能把本地完整路径暴露给网页脚本。你要是能在网页里读取C:\Users\张三\Desktop\xxx.docx那任何恶意站点都能偷窥本地文件分布了所以浏览器对文件对象做了严格裁剪你拿到的文件对象有名字、大小、类型、修改时间但绝对路径一律不给你。HTML5 的webkitdirectory属性走的是另一条路它允许用户选择整个文件夹然后浏览器把所有文件对象展开成列表并且额外提供一个相对路径字段webkitRelativePath。这个相对路径是从用户选择的根目录开始算的比如选了 D 盘下的项目资料文件夹里面文件可能是项目资料/2024/合同/扫描件.pdf这样的格式。浏览器只给你相对路径不泄露根目录在磁盘上的具体位置既满足了业务需要又守住了安全底线。1.3 国产化环境放大了哪些问题这件事在普通 Windows Chrome 环境下可能半小时就调通了换到信创环境就变数丛生。首先是浏览器内核差异有的终端用的是较新的 Chromium 内核有的还在维护老内核专属版本webkitRelativePath是否可用、File 对象是否完整都不一定。其次是操作系统差异不同发行版的文件系统对路径分隔符、大小写、中文字符的处理规则不完全一致。再有就是部署环境复杂系统可能被嵌在门户 iframe 里、经过统一身份认证跳转路径信息可能在转发过程中被吞掉。一句话总结单机 Chrome 里验证通过的方案放在信创终端矩阵里要重新打三个补丁——兼容性检测、路径清洗、降级策略。下文逐个展开。2. 从 input 开始的路径采集webkitdirectory 和 webkitRelativePath 是核心底牌2.1 文件夹是怎么被展开成文件列表的先看最基本的实现把input加上webkitdirectory属性用户点击后弹出的就不是文件多选而是文件夹选择器。input typefile idfolderInput webkitdirectory /用户选了文件夹后input.files里不是只有文件夹对象而是这个文件夹下所有递归文件的扁平列表。举个例子用户选择了一个叫项目A的文件夹里面结构是项目A/ 批复/ 001.txt 合同/ 附件/ 图纸.pdf选择后input.files里会有三个文件对象每个文件对象上除了常规的name、size、type、lastModified还会多一个webkitRelativePath项目A/批复/001.txt项目A/合同/附件/图纸.pdf这里的关键点在于浏览器在用户完成选择那一刻就基于所选根目录自动拼好了相对路径。前端要做的第一件事就是遍历文件列表时把这个字段原样保留下来别在后续处理里丢了。采集代码可以这样写const input document.getElementById(folderInput); input.addEventListener(change, (e) { const files Array.from(e.target.files || []); const meta files.map((file) { return { name: file.name, size: file.size, lastModified: file.lastModified, relativePath: (file.webkitRelativePath || ).replace(/\\/g, /), }; }); console.log(文件总数:, meta.length); console.log(路径样例:, meta.slice(0, 3).map((m) m.relativePath)); });注意这里我把\统一替换成了/原因后面会在踩坑部分细说但建议从第一天就强制统一分隔符否则 Windows 终端的路径和国产 Linux 终端的路径会在后端发生错乱。2.2 路径字符串要怎么清洗才敢传给后端浏览器给的前路径那么好用是不是可以直接拼到后端文件系统里绝对不行。webkitRelativePath虽然安全剔除了绝对路径但用户选中的文件夹本身可能就叫../或者包含特殊字符。如果不做清洗直接拿这个字段去拼接服务器目录就给了路径穿越的机会。我建议的前端清洗规则有三条强制把分隔符统一成/去掉开头的/或盘符格式如C:逐段检查目录名拒绝空串、.、..、以及含控制字符的段具体可以这样清洗function normalizeAndValidateRelativePath(rawPath) { let p (rawPath || ).replace(/\\/g, /); p p.replace(/^\//, ); p p.replace(/^[a-zA-Z]:\//, ); if (!p) return ; const segments p.split(/); if (segments.some((seg) !seg || seg . || seg ..)) { throw new Error(上传路径包含非法目录段); } return segments.join(/); }清洗后每个文件对应一个形如项目A/合同/附件/图纸.pdf的相对路径。我要强调一个容易被忽略的点这里的前端清洗只是第一道关后端必须再做一遍同样严格甚至更严格的校验因为接口可以被绕过不能指望前端传什么都是干净的。2.3 为什么说 File System Access API 在信创终端基本不可用有些开发者会想既然webkitRelativePath是老 API能不能用更新的 File System Access API就是showDirectoryPicker()那个。它的确能拿到目录句柄和更灵活的文件读写能力但我在信创终端上实测下来覆盖情况不乐观。不少国产浏览器还是基于较老的内核分支对 File System Access API 没有启用或者只实现了部分能力。所以现实选择是在信创环境里做文件夹上传主路径必须依赖input[webkitdirectory]webkitRelativePathFile System Access API 顶多作为增强特性在检测到支持时再启用绝不能让主流程依赖它。检测方式也很简单const canUseDirectoryPicker showDirectoryPicker in window; const canUseWebkitDirectory webkitdirectory in document.createElement(input);如果两条路都不通就得走降级方案这个放在后面的安全边界章节展开。3. 端到端保留路径前端传参、后端重建目录树的完整链路3.1 每个文件都必须带上自己的“相对地址”很多人做上传表单时习惯用一个FormData循环 append 文件但路径信息并不会随着append(files[], file)自动传上去。FormData的append方法里第三个参数虽然能指定文件名但它只接受简单的文件名不能带路径分段传了路径也会被浏览器做成 basename。我这边用的方案是文件按顺序 append 的同时往一个平行的paths[]字段里按相同索引 append 相对路径。后端按索引一一对应就能恢复每个文件的路径。async function uploadFolder(files) { const formData new FormData(); for (const file of files) { const cleanPath normalizeAndValidateRelativePath(file.webkitRelativePath || file.name); formData.append(files[], file, file.name); formData.append(paths[], cleanPath); } // 用 XHR 而不是 fetch因为 fetch 拿不到上传进度 return new Promise((resolve, reject) { const xhr new XMLHttpRequest(); xhr.open(POST, /api/upload/folder); xhr.upload.addEventListener(progress, (evt) { if (evt.lengthComputable) { const percent Math.round((evt.loaded / evt.total) * 100); console.log(上传进度:, percent %); } }); xhr.onload () { if (xhr.status 200 xhr.status 300) { resolve(JSON.parse(xhr.responseText)); } else { reject(new Error(上传失败HTTP xhr.status)); } }; xhr.onerror () reject(new Error(网络异常)); xhr.send(formData); }); }这里的file.name作为append的第三个参数仍然要传作用是保留原始文件名防止有些后端框架拿不到文件名做拓展名判断真正的目录路径则走paths[]。两个数组的下标严格一致这是整个方案最核心的约定。3.2 后端重建目录树物理落盘和逻辑展示两条路线后端拿到files[]和paths[]之后需要区分两种诉求一种是业务要求文件真的按目录结构落盘到服务器某个目录下另一种是文件存储在对象存储或统一存储里只需要在数据库里保留路径信息、页面展示时再重建虚拟目录树。先看物理落盘的逻辑。比如用 Node.js 实现收到文件后按路径逐级创建目录再写入文件const fs require(fs); const path require(path); function sanitizePath(rawPath) { let p rawPath.replace(/\\/g, /).replace(/^\//, ); if (/^[a-zA-Z]:/.test(p) || p.includes(..) || p.includes(\0)) { throw new Error(非法路径); } return p; } async function saveFileWithPath(baseDir, rawPath, buffer) { const cleanPath sanitizePath(rawPath); const targetFile path.join(baseDir, cleanPath); if (!targetFile.startsWith(path.resolve(baseDir))) { throw new Error(路径越界); } await fs.promises.mkdir(path.dirname(targetFile), { recursive: true }); await fs.promises.writeFile(targetFile, buffer); return cleanPath; }这段代码里有个细节值得关注targetFile.startsWith(path.resolve(baseDir))的二次校验。第一次校验已经挡掉了..和绝对路径但为了防御多层符号链接、特殊组合目录的情况再加一道前缀校验更稳妥。凡是涉及把用户可写路径映射为服务器本地路径的场景必须坚持“清洗层 前缀校验层”双保险。再看逻辑目录树。如果文件本身已经进了对象存储后端只需要把路径字符串存进数据库然后提供接口按路径组装树形结构。前端请求一次就能拿到嵌套的 JSONfunction buildTreeFromPaths(paths) { const root { name: /, type: dir, children: [] }; for (const p of paths) { const segments p.split(/).filter(Boolean); let current root; segments.forEach((seg, index) { const isFile index segments.length - 1; let child current.children.find( (item) item.name seg item.type (isFile ? file : dir) ); if (!child) { child { name: seg, type: isFile ? file : dir, children: [] }; current.children.push(child); } current child; }); } return root; }这里我没有用嵌套 Map 的写法是因为目录层级的展示顺序要保持稳定用数组find虽然看起来是线性查找但实际文件层级深度通常不超过 10 层性能完全够用。真遇到几千个子目录的极端场景再换成按路径前缀分组排序的方案也不迟。3.3 虚拟目录树怎么在页面上还原给用户上传完成后页面上的展示如果还是扁平的文件列表业务人员不会有“路径保留成功”的实感。所以我在项目里做了一个目录树组件把后端返回的树形 JSON 渲染成可折叠的树。用户传完就能看到自己本地的项目A/合同/附件/图纸.pdf在系统里也保持着同样的层级体验和信任感立刻不一样。渲染树本身有两种做法一是后端直接返回嵌套 JSON前端递归渲染二是后端只返回平铺路径列表前端用buildTreeFromPaths自己组装。我推荐后端返回平铺列表前端组装树这样以后接对象存储、导出清单、全文检索时平铺数据更灵活。一个可用的渲染思路是把树节点渲染成缩进排列的行目录节点显示箭头可展开文件节点行内显示文件名、大小、上传时间和操作按钮。控制展开状态不需要引入重型树组件维护一个Set存展开的节点路径即可。4. 实测踩坑记录五个让路径消失的常见场景4.1 拖拽上传让路径信息蒸发项目第一版上线前我出于“用户体验”考虑加了一个拖拽上传区允许用户把文件夹直接拖到页面上。本地 Chrome 测试一切正常文件夹拖上去居然也有相对路径。结果在客户那台国产终端上一试路径全部丢失所有文件变成根目录下的平铺文件。排查过程是这样的先对比了拖拽和点击选择的File对象发现点击选择走的是input[webkitdirectory]浏览器会触发目录模式给每个文件补上webkitRelativePath而拖拽走的是DataTransfer国产浏览器没有实现DataTransferItem.webkitGetAsEntry接口导致我递归解析目录结构的代码根本执行不到。最后方案是把拖拽入口直接改成“选择文件夹”按钮触发真实 input拖拽区域只保留对普通文件的兼容文件夹拖入时弹提示让用户改用按钮。别看这个改动小它省掉了我后续可能要维护的多套解析逻辑。在信创环境里能用input[webkitdirectory]就尽量别自创一套目录解析。4.2 分隔符与大小写带来的目录错位第二个坑发生在路径重建阶段同一个文件在 Windows 终端传上来是项目A\合同\附件\图纸.pdf在国产 Linux 终端传上来变成项目A/合同/附件/图纸.pdf后端拿到手没有统一格式化就直接用它去拼接目录了结果 Windows 终端上传的文件在 Linux 服务器上出现了带反斜杠字面量的文件夹名目录树彻底乱了。更隐蔽的是大小写问题有的终端文件系统大小写敏感有的不敏感。同一个目录名一个终端写Attachment另一个终端程序里写attachment重建目录时可能创建出两个文件夹。我的应对办法非常朴素前端在采集时统一replace(/\\/g, /)后端在入口处再统一执行一次同样替换目录名校验时用“原样保存路径”而不是“转换为小写保存路径”但要给用户文件名和相对路径另加一层唯一索引避免因大小写造成同路径文件覆盖。不要试图猜测操作系统的行为定死一条规则比兼容所有规则更可靠。4.3 同名目录合并导致文件串层这个坑在逻辑目录树阶段最典型。业务人员第一天传了项目A/合同/附件的文件第二天又传了项目B/合同/附件的文件看起来没问题但代码里如果把两个批次的数据塞进同一棵树buildTreeFromPaths会把合同和附件目录合并成同一个节点两个项目的附件被混到一个目录下面。如果文件名字还一样直接互相覆盖。排查链路是我先怀疑后端存路径时去重条件写得不对查了数据库发现根本原因是前端在组装树时没有区分批次。后来我在路径数据里增加了一个“批次ID”维度每次上传会话生成一个唯一批次号树形组装的根节点下第一层始终是批次节点。界面上一是展示“上传批次”分组二是允许业务人员按批次核对路径这个设计后来在客户演示时收到了不错的效果。核心原则目录树组装之前先想清楚“你是按路径合并还是按上传会话隔离”。按业务需要选择不要默认全合并。4.4 跨域 iframe 传输时 File 对象失真我们的系统很多时候不是独立部署而是嵌在单位内部门户的 iframe 里。门户系统与子系统域名不同通信通常靠postMessage。我遇到过一种奇特的丢路径现象用户在 iframe 里选择了文件夹数据交给父页面后父页面再提交任务结果上传到后端的文件路径全变成了unknown。逐步排查后发现子页面把File对象通过postMessage发给了父页面。结构化克隆算法在某些浏览器里虽然支持传输File对象但传输过去后webkitRelativePath字段直接丢失了只剩name和size。父页面那边再做一次FormData.append路径信息早就没了。修复方式很简单不要在跨域 iframe 之间传File对象也不要在父页面二次构造上传数据。上传请求必须在拿到文件夹选择的那个 iframe 内部直接发出父页面只接收“上传完成”的通知和结果数据。这条经验适用于任何有跨域嵌套的微前端、门户场景。4.5 内核版本不同导致元数据缺失还有一个最直白的坑一台终端安装的国产浏览器内核版本较旧打开系统后change事件里file.webkitRelativePath是undefined整个页面的路径采集逻辑全部失效。我当时第一反应是代码问题但同样的代码在另一台新内核终端上完全正常。排查方式是在页面上输出浏览器版本号、UA、navigator.userAgent再用不同的终端做对照发现只有版本较老的内核分支存在问题。因为该浏览器在编译时没有完整启用 File API 的目录元数据属于能力缺失不是代码能绕过的。最后我只能做两层处理第一层在页面加载时动态检测File.prototype.webkitRelativePath如果缺失就提示用户“当前浏览器不支持目录路径保留请安装新版浏览器或切换其他浏览器”第二层是提供降级上传入口用户即使没有路径也能把文件传上去业务上按“未知来源目录”统一归档处理。信创终端矩阵本来就杂别赌所有终端能力一致一定要有降级路线。5. 路径保留之外的安全边界与降级策略5.1 路径穿越是一道必须守住的底线只要用户输入路径就必然会面临路径穿越攻击。比如用户手动构造一个relativePath为../../etc/crontab如果后端直接用path.join(baseDir, relativePath)落盘就可能写到预期目录之外。这个风险不只在文件夹上传场景存在凡是“用户可提交路径 服务器目录拼接”的组合都要警惕。我总结了一套固定防线路径字段禁止以/开头禁止匹配盘符正则禁止出现..段必须在“清洗后的路径”基础上再做一次resolve和startsWith(baseDir)校验路径中只允许包含常见中英文字符、数字、点、短横线、下划线、空格和小括号其他字符一律拒绝对单个文件大小、路径总长度分别做上限限制超长路径直接报错而不是截断落盘目录的权限要收紧只给运行进程最小读写权限我见过有些项目图省事把relativePath原样存数据库下载时再拼接一次路径生成下载地址。这种“二次拼接”风险更高因为中间任何一次粗心都可能把..带进去。所以我更推荐数据库存储时就用清洗后的标准化路径并且提供独立的下载适配层。5.2 不支持相对路径时怎么办前面提到的旧内核浏览器、拖拽场景、跨域 iframe都可能让前端拿不到可靠的webkitRelativePath。这种情况下有没有能保留目录结构的替代方案我试过三种方式按推荐度排序第一种是要求升级浏览器或切换浏览器适合内部系统能统一终端的场景。很多信创项目其实可以约定浏览器版本白名单这比做代码兼容更省心。第二种是把文件夹压缩成 zip 上传后端解压后通过 zip 内部的相对路径重建目录。压缩包里的路径是用户本地压缩时生成的可靠度很高适合离线资料、超大文件夹场景。第三种是提供一个“目录说明文件”上传项让用户把文件夹里的目录说明.txt或者手工填写的路径清单一起传上来系统按清单映射路径。这个适合存量历史数据导入。在我实际项目里降级策略最终是按终端能力动态分区检测到支持webkitdirectory就用原生文件夹选择检测不到就引导用户压缩上传少部分顽固场景保留手动建目录功能。三条路并存后运维人员的工单明显减少了。5.3 空目录、长路径、大文件这些边缘情况文件夹上传的路径保留方案里边缘情况真的要测试到位不然上线后问题全集中在业务高峰。空目录是一个容易忽略的点。用户明明建了个空目录想在系统里一起保留但input.files只包含文件空目录根本不会出现在文件列表里后端自然不知道有这个目录存在。我一开始没处理后来业务人员说“空目录怎么老丢”才意识到选择文件夹时浏览器压根不会上报空目录。解决方案是允许用户在系统里手动创建目录节点或者增加一个“保留空目录”的辅助文件约定比如目录下放一个.keep占位文件上传时识别到.keep就创建目录但不展示该文件。超长路径也比较麻烦。Windows 传统路径有 260 字符限制国产 Linux 发行版对文件名和路径长度限制倒宽松些但 NTFS、FAT 这些文件系统仍然有约束。我在验证时用一个 180 字符的文件名直接触发了服务端写入失败。后来对路径长度做了预检超过限制的路径直接提示用户重命名不再继续写。大文件、多文件量级也要提前设计。一个文件夹里几千个文件前端一个个 append 到FormData时内存会涨得很快建议分批发送每批控制在 200 个文件以内并显示批次进度。路径保留与分片上传结合时还要注意每个分片都要携带同一个relativePath否则服务端合并文件时无法确定归属目录。6. 我在信创适配过程中积累的几点经验最后分享几个偏“软”的经验这些不在技术文档里写但实际项目里价值很大。第一个是需求澄清必须前置。接到“文件夹上传保留路径”这类需求时先问清楚业务方要的“路径”是给人看的虚拟目录树还是给系统落盘用的真实目录结构。这两个方向的实现成本完全不同前者不用碰服务器文件系统后者牵扯到磁盘布局、权限、备份策略。我在项目里花了半天做这个澄清后面少走了很多弯路。第二个是终端兼容性要做矩阵化测试。百闻不如一见哪怕同品牌浏览器不同版本File 对象能力都可能不一样。我这边专门整理了一张表格把常见的国产化操作系统、浏览器内核版本、webkitdirectory支持情况、webkitRelativePath是否可用、拖拽是否支持逐项打勾。每次新接到一台终端先跑一遍探测脚本再决定启用哪条上传路径。第三个是给用户界面做足“路径可见性”设计。技术上路径保住了如果页面上呈现的还是平铺文件列表业务方感知不到成果。我在上传成功后做了一个“上传结果预览”自动按路径整理成可折叠文件夹树并附上“上传成功 X 个文件路径完整保留”的提示。就是这么一个小细节让客户验收时立刻认可了这项工作。这个需求做完后我自己最大的体会是所谓适配很多时候不是实现一个“最好”的方案而是找到一条在最多环境里都“不会坏”的主路径再给少数特殊环境留活口。webkitdirectorywebkitRelativePath这条路在信创终端里不算新但它简单、可靠、覆盖广加上合理的清洗、校验和降级设计就能把“保留文件夹上传路径”这个需求稳稳落地。
