纯前端实现OSS文件多级目录批量导出方案

引言：在现代Web应用开发中，我们常需处理云端文件与本地文件系统的交互需求。本文聚焦一个典型场景：​如何通过纯前端技术，将OSS（对象存储服务）中的文件按原有路径结构批量导出至用户本地设备。该方案需满足两个核心诉求：

1. 保持云端文件层级关系（如oss://project/docs/2025/file1.pdf对应本地/project/docs/2025目录）
2. 规避浏览器安全限制，实现一键式安全下载

问题挑战：浏览器的安全边界

浏览器作为沙箱化执行环境，出于安全考虑严格限制以下操作：

• ​禁止自由访问文件系统：无法直接读取/写入任意本地路径
• ​限制批量下载行为：传统下载方式会导致多文件弹窗频现
• ​阻断目录结构操作：无法以编程方式创建本地文件夹层级

  这些限制使得传统的标签下载或window.open方案难以满足需求，亟需探索新的技术路径。

   

   使用​File System API前端本地化处理文件下载案例截图（案例代码下拉到底部）：

  

  创建了文件并实时写入了数据

  

   

  Web端多文件下载技术方案对比：

  • 后端集中式处理：

    • 实现逻辑：
      • 用户在前端选择目标文件/目录 → 发送批量下载请求 → 后端异步拉取OSS文件并构建目录结构 → 服务端生成ZIP压缩包 → 返回下载链接 → 前端通过标签触发下载（典型应用：百度网盘Web端）

      • ✅ ​优势：

        • 服务端高性能处理，支持海量文件（如TB级数据）
        • 天然规避浏览器内存限制，稳定性强
        • 统一权限校验与日志审计，符合企业级安全要求

        • ❌ ​劣势：

          • 服务端资源消耗大（计算、存储、带宽成本）

          • 异步处理导致延迟（用户需等待打包完成）

          • 无法实现纯前端离线操作

          • ​前端本地化处理

            • 方案一：内存压缩流方案（JSZip类库）​

              • 技术路径：

                • 批量获取文件二进制流（Blob）
                • 在内存中构建虚拟文件树（模拟目录层级）
                • 使用JSZip生成ZIP包并触发浏览器下载
                • ✅ ​优势：
                  • 纯前端实现，零服务端依赖
                  • 实现轻量化，对小文件场景友好（ { const url = window.URL.createObjectURL(blob); downloadFile(url, "test.zip"); });

                  • 方案二：使用File System API：

                    • 技术路径：

                      • 调用window.showDirectoryPicker()获取用户授权

                      • 创建沙盒化虚拟文件系统（非真实磁盘路径）

                      • 通过Streams API流式写入文件并保持路径元数据

                      • ✅ ​优势：

                        • ​用户控制：通过显式授权机制保障用户知情权，避免隐蔽操作风险
                        • ​本地化交互：支持本地文件实时编辑与保存，减少上传/下载环节
                        • ​大文件友好：基于文件流的分块写入机制降低内存压力

                        • ❌ ​劣势：

                          • ​兼容性局限：仅Chromium内核浏览器全功能支持（Chrome/Edge ≥ 86）
                          • ​权限模型复杂：需处理权限持久化（如handle.persist()）
                          • ​沙箱隔离：生成文件无法直接访问系统路径（需用户手动导出）
                          • 

                            方案选型建议：

                            维度	后端方案	前端JSZip方案	前端File API方案
                            ​适用场景	企业级海量数据	中小型即时导出	本地编辑型应用
                            ​性能边界	无上限	{ const { loaded, total } = progressEvent; const progress = total ? (loaded / total) * 100 : 0; console.log(`Download progress: ${progress}%`); } }); console.log('Response headers from OSS:', response.headers); const contentDisposition = response.headers['content-disposition']; let fileName = 'unknown'; if (contentDisposition) { const fileNameMatch = contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/); if (fileNameMatch != null && fileNameMatch[1]) { // Decode the filename fileName = decodeURIComponent(fileNameMatch[1].replace(/['"]/g, '')); } } if (fileName === 'unknown') { const parsedUrl = new URL(ossEndpoint); fileName = path.basename(parsedUrl.pathname); } res.set({ 'Content-Type': response.headers['content-type'], 'Content-Length': response.headers['content-length'], 'Content-Disposition': `attachment; filename=${fileName}`, 'Access-Control-Expose-Headers': 'Content-Disposition' }); // 这里我们监听数据流事件来监控下载进度 let dataLength = 0; const totalLength = parseInt(response.headers['content-length'], 10); response.data.on('data', chunk => { dataLength += chunk.length; const progress = totalLength ? (dataLength / totalLength) * 100 : 0; console.log(`Download progress: ${progress.toFixed(2)}%`); }); response.data.pipe(res); } catch (error) { console.error('Error fetching OSS link:', error); res.status(500).json({ error: 'Failed to fetch OSS link' }); } }); app.listen(port, () => { console.log(`Server running at http://localhost:${port}`); });  web调用API并写入数据 文件系统API操作示例 下载文件到指定目录 下载进度: 0% // 主操作流程 =================================================== document.getElementById('createFileButton').addEventListener('click', async () => { const start = performance.now(); try { // 阶段1: 获取目录权限 const dirHandle = await requestDirectoryAccess(); // 阶段2: 创建下载目录 const targetDirHandle = await createDownloadDirectory(dirHandle); // 阶段3: 获取云端文件 const fileResponse = await fetchOSSFile(); // 阶段4: 解析文件信息 const { fileName, fileSize } = await analyzeFileMetadata(fileResponse); // 阶段5: 创建本地文件 const fileHandle = await initializeLocalFile(targetDirHandle, fileName); // 阶段6: 流式写入数据 await streamDataToFile(fileHandle, fileResponse, fileSize); } catch (error) { handleOperationError(error); } finally { // 性能监控日志 const duration = performance.now() - start; console.log(`[性能] 操作耗时: ${duration.toFixed(2)}ms`); } }); // 核心功能函数 ================================================ /** * 请求文件系统访问权限 * @returns {Promise} */ async function requestDirectoryAccess() { try { return await window.showDirectoryPicker({ mode: 'readwrite', // 明确请求读写权限 startIn: 'downloads' // 建议起始目录（部分浏览器支持） }); } catch (error) { throw new Error(`目录访问被拒绝: ${error.message}`); } } /** * 创建下载专用目录 * @param {FileSystemDirectoryHandle} parentDir * @returns {Promise} */ async function createDownloadDirectory(parentDir) { try { return await parentDir.getDirectoryHandle('oss-downloads', { create: true, // 自动创建目录 recursive: true // 确保递归创建（如果父目录不存在） }); } catch (error) { throw new Error(`目录创建失败: ${error.message}`); } } /** * 获取云端文件数据 * @returns {Promise} */ async function fetchOSSFile() { try { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); // 10秒超时 const response = await fetch('http://localhost:3000/get-oss-link', { signal: controller.signal }); clearTimeout(timeoutId); if (!response.ok) { throw new Error(`请求失败: HTTP ${response.status}`); } return response; } catch (error) { throw new Error(`文件获取失败: ${error.message}`); } } /** * 解析文件元数据 * @param {Response} response * @returns {Promise} */ async function analyzeFileMetadata(response) { // RFC 6266标准的文件名解析 const disposition = response.headers.get('Content-Disposition') || ''; const filenameRegex = /filename\*?=(?:utf-8''|")?([^";]+)/i; const matchResult = disposition.match(filenameRegex); // 安全获取文件名 let filename = matchResult?.[1] ? decodeURIComponent(matchResult[1]) : new URL(response.url).pathname.split('/').pop() || '未命名文件'; // 消毒处理文件名 filename = sanitizeFilename(filename); // 获取文件尺寸 const fileSize = Number(response.headers.get('Content-Length')) || 0; console.log(`[元数据] 文件名: ${filename}, 大小: ${formatBytes(fileSize)}`); return { fileName: filename, fileSize }; } /** * 初始化本地文件 * @param {FileSystemDirectoryHandle} dirHandle * @param {string} fileName * @returns {Promise} */ async function initializeLocalFile(dirHandle, fileName) { try { return await dirHandle.getFileHandle(fileName, { create: true, // 创建新文件 keepExistingData: false // 覆盖已存在文件 }); } catch (error) { throw new Error(`文件创建失败: ${error.message}`); } } /** * 流式写入文件数据 * @param {FileSystemFileHandle} fileHandle * @param {Response} response * @param {number} totalSize */ async function streamDataToFile(fileHandle, response, totalSize) { const progressBar = document.getElementById('download-progress'); const progressText = document.getElementById('download-progress-text'); let receivedBytes = 0; let lastUpdate = 0; // 用于节流进度更新 try { const writable = await fileHandle.createWritable({ keepExistingData: false }); const reader = response.body.getReader(); while (true) { const { done, value } = await reader.read(); if (done) break; receivedBytes += value.length; await writable.write(value); // 节流进度更新（每秒最多60次） const now = Date.now(); if (now - lastUpdate > 16) { updateProgressIndicator(receivedBytes, totalSize, progressBar, progressText); lastUpdate = now; } } // 最终进度同步 updateProgressIndicator(receivedBytes, totalSize, progressBar, progressText); } finally { if (writable) await writable.close(); } } // 辅助工具函数 ================================================ /** * 统一错误处理 * @param {Error} error */ function handleOperationError(error) { console.error('[错误]', error); alert(`操作失败: ${error.message.replace(/^[^:]+: /, '')}`); } /** * 更新进度指示器 * @param {number} current * @param {number} total * @param {HTMLElement} bar * @param {HTMLElement} text */ function updateProgressIndicator(current, total, bar, text) { const percentage = total ? Math.min((current / total) * 100, 100) : 0; bar.value = percentage; text.textContent = `下载进度: ${percentage.toFixed(1)}% - ${formatBytes(current)}/${formatBytes(total)}`; } /** * 文件名消毒处理 * @param {string} name * @returns {string} */ function sanitizeFilename(name) { return name .replace(/[/\\?*:|"]/g, '_') // 替换非法字符 .normalize('NFC') // 统一Unicode格式 .substring(0, 200) // 限制最大长度 .trim() || '未命名文件'; // 处理空文件名 } /** * 字节格式化工具 * @param {number} bytes * @returns {string} */ function formatBytes(bytes) { if (bytes === 0) return '0 B'; const units = ['B', 'KB', 'MB', 'GB']; const exponent = Math.floor(Math.log(bytes) / Math.log(1024)); return `${(bytes / 1024 ** exponent).toFixed(2)} ${units[exponent]}`; } 案例实现：用户授权可操作的文件夹 → 创建保存下载文件的目录 → 请求文件数据 → 解析文件信息 → 创建本地文件 → 流式写入数据    总结：基于浏览器 File System Access API，实现目录体系构建、文件全生命周期管理与流式数据写入三大核心能力。在实际业务场景中可根据API提供的能力进行定制化开发，实现多种文件交互的复杂场景。