详细讲解浏览器不支持showDirectoryPicker时如何用JavaScript选择文件夹:涵盖特性检测与安全上下文判断、input webkitdirectory标准降级方案、拖拽webkitGetAsEntry递归遍历目录树,以及统一封装示例与常见边界问题处理。
浏览器不支持showDirectoryPicker时JS怎么选择文件夹
时间:2026-11-22
浏览:494
文章目录
当浏览器不支持 window.showDirectoryPicker() 时,前端最稳妥的替代做法是使用带 webkitdirectory 属性的 <input type="file"> 读取文件夹内的全部文件及相对路径;如果希望在桌面端支持直接把文件夹拖入页面,可以配合 DataTransferItem.webkitGetAsEntry() 递归遍历目录树,并将不同来源统一整理为 { path, file } 结构供后续业务使用。
很多前端项目在开发阶段使用桌面端 Chromium 内核浏览器调试,直接写一行 await window.showDirectoryPicker() 就能弹出目录选择框;但上线后换用 Safari、Firefox,或者测试同学通过内网 http://192.168.x.x 地址访问时,点击按钮却毫无反应,控制台直接抛出 window.showDirectoryPicker is not a function。
要把这件事处理干净,不能只靠简单的 if/else 替换,还需要分清楚“API 根本不存在”“环境限制导致不可用”和“用户自己点了取消”三种情况,再对接不同的降级方案。
先区分“不支持”与“用户取消”:准确检测与降级时机
在决定走降级逻辑之前,先确认 showDirectoryPicker 为什么不可用。目前只有部分桌面现代浏览器实现了 File System Access API,而在 Firefox、Safari、多数移动端浏览器以及非安全上下文中,这个接口都不会暴露到 window 上。
- API 未实现:
typeof window.showDirectoryPicker !== 'function',常见于不支持该规范的浏览器或部分内置 WebView。 - 非安全上下文:当页面运行在非
localhost的普通http://协议下时,window.isSecureContext为false,即便浏览器内核本身支持该 API,window.showDirectoryPicker也会是undefined。 - iframe 沙箱或权限策略拦截:如果页面嵌在跨源
<iframe>中,或响应头配置了严格的Permissions-Policy,API 函数可能存在,但调用时会同步或异步抛出SecurityError。 - 用户主动取消选择:弹窗已经正常打开,用户点击了“取消”或按下 Esc 键,此时会抛出
name === 'AbortError'的DOMException。
容易出错的地方:不要在 catch (err) 里不加区分地直接打开降级文件框。如果用户刚刚在原生目录选择器里主动点了“取消”(AbortError),你的代码又马上弹出一个传统文件选择框,会造成反复弹窗的糟糕体验。只有特性检测失败,或者捕获到 SecurityError、NotAllowedError 等环境限制错误时,才应当回退。
方案一:使用 <input type="file" webkitdirectory>(最通用的降级方案)
在不支持 showDirectoryPicker 的浏览器中,给 <input type="file"> 加上 webkitdirectory 属性是目前兼容性最广的替代方式。虽然属性名字带有 webkit 前缀,但 Firefox、Safari 以及各类基于 Chromium 的桌面浏览器都已经支持它。
用户选定一个文件夹后,浏览器不会返回目录句柄,而是直接把这个文件夹及其所有子目录里的文件扁平化,放进 input.files 这个 FileList 中。每个 File 对象上都会多出一个 webkitRelativePath 属性,记录了从所选根目录开始到当前文件的完整相对路径,例如 "my-project/src/utils/format.js"。
<!-- 建议同时保留 webkitdirectory、directory 与 multiple -->
<input id="dirInput" type="file" webkitdirectory directory multiple hidden />
<button id="pickBtn" type="button">选择文件夹</button>
<script>
const dirInput = document.getElementById('dirInput');
const pickBtn = document.getElementById('pickBtn');
pickBtn.addEventListener('click', () => {
// 每次打开前清空 value,避免用户重复选择同一个文件夹时不触发 change
dirInput.value = '';
dirInput.click();
});
dirInput.addEventListener('change', (event) => {
const files = Array.from(event.target.files || []);
const result = files.map((file) => ({
// 部分移动端环境若不支持目录选择,webkitRelativePath 可能为空字符串
path: file.webkitRelativePath || file.name,
file,
}));
console.log('读取到的文件数量:', result.length);
console.log(result.slice(0, 5));
});
</script>
读取到的文件数量: 3
[
{ path: "docs/README.md", file: File(...) },
{ path: "docs/guide/intro.md", file: File(...) },
{ path: "docs/assets/logo.png", file: File(...) }
]
使用 webkitdirectory 时,有三个细节直接决定后续逻辑会不会出错:
- 空文件夹不会出现:因为
input.files只收集文件实体,如果某个子文件夹里没有任何文件,它不会以任何形式出现在列表里。需要还原文件夹树结构时,只能通过webkitRelativePath里的斜杠/反推出有文件的目录层级。 - 重复选择同一目录要清空
value:如果不先执行dirInput.value = '',用户修改了文件夹里的某个文件并再次选择同一目录,浏览器可能认为选中路径没变而跳过change事件。 - 移动端浏览器存在退化可能:部分手机浏览器或内置 WebView 会忽略
webkitdirectory,直接把控件当成普通多选或单选文件框弹出。所以代码中写file.webkitRelativePath || file.name作为兜底,至少能保证单文件读取不至于报错崩溃。
方案二:拖拽文件夹并用 webkitGetAsEntry() 递归读取
如果产品场景是在桌面端让用户把文件夹直接拖进网页区域,或者确实需要感知“空目录”的存在,仅靠 input[webkitdirectory] 不够用,这时可以结合 HTML5 拖放事件里的 DataTransferItem.prototype.webkitGetAsEntry()。
当文件夹被拖入页面并触发 drop 事件时,不能只看 e.dataTransfer.files(有些浏览器在拖拽文件夹时只会把文件夹当成一个长度为 0 的无效文件条目),而是要读取 e.dataTransfer.items,把每一项转成 FileSystemEntry 再递归展开。这个 API 在桌面端 Chrome、Edge、Firefox 和 Safari 中都有广泛实现。
写这段递归代码时,有两个地方最容易踩坑:
- 必须在
drop事件同步执行阶段把所有 Entry 全部取出:浏览器会在drop事件回调函数返回后立即清空dataTransfer.items。如果你先await了第一个文件夹再回头去读第二个items[i],后面的项都会变成null。 readEntries()每次只返回部分条目:拿到目录的读取器dirEntry.createReader()后,调用一次reader.readEntries()并不保证把目录下所有文件一次性返回(在常见浏览器实现里,单批上限通常为 100 条)。必须循环调用readEntries(),直到某一次返回空数组[]才表示这个目录已经读完。
下面是完整的拖拽目录解析代码,直接放在浏览器页面中即可运行:
<div id="dropZone" style="border: 2px dashed #52677d; padding: 32px; text-align: center;">
把文件夹拖到这里
</div>
<script>
const dropZone = document.getElementById('dropZone');
// 必须阻止 dragover 默认行为,否则浏览器不会触发 drop,而是直接打开拖入的文件
dropZone.addEventListener('dragover', (e) => {
e.preventDefault();
});
dropZone.addEventListener('drop', async (e) => {
e.preventDefault();
// 关键:在 await 之前同步取出所有 entry
const items = Array.from(e.dataTransfer.items || []);
const entries = items
.filter((item) => item.kind === 'file' && typeof item.webkitGetAsEntry === 'function')
.map((item) => item.webkitGetAsEntry())
.filter(Boolean);
const files = [];
const emptyDirs = [];
for (const entry of entries) {
await collectEntry(entry, '', files, emptyDirs);
}
console.log('拖拽读取到的文件:', files);
console.log('空目录路径:', emptyDirs);
});
async function collectEntry(entry, parentPath, files, emptyDirs) {
const currentPath = parentPath ? `${parentPath}/${entry.name}` : entry.name;
if (entry.isFile) {
const file = await new Promise((resolve, reject) => entry.file(resolve, reject));
files.push({ path: currentPath, file });
return;
}
if (entry.isDirectory) {
const children = await readAllDirectoryEntries(entry.createReader());
if (children.length === 0) {
emptyDirs.push(currentPath);
return;
}
for (const child of children) {
await collectEntry(child, currentPath, files, emptyDirs);
}
}
}
function readAllDirectoryEntries(reader) {
return new Promise((resolve, reject) => {
const allEntries = [];
function readBatch() {
reader.readEntries((batch) => {
if (batch.length === 0) {
resolve(allEntries);
} else {
allEntries.push(...batch);
readBatch();
}
}, reject);
}
readBatch();
});
}
</script>
把 showDirectoryPicker 与降级方案封装成统一入口
在实际业务里,无论是上传代码包、批量导入图片还是在线解析配置文件,上层代码通常只想要一个扁平的文件数组。把 showDirectoryPicker 和 input[webkitdirectory] 包装到同一个函数 pickDirectoryFiles() 里,就能做到在支持新 API 的浏览器走新接口,不支持或受限时自动退回传统文件夹选择。
<button id="selectFolderBtn" type="button">选择文件夹并读取</button>
<pre id="output"></pre>
<script>
/**
* 统一选择文件夹并返回 [{ path, file }] 数组
* 用户主动取消时返回 null
*/
async function pickDirectoryFiles() {
const canUsePicker =
typeof window.showDirectoryPicker === 'function' && window.isSecureContext;
if (canUsePicker) {
try {
const dirHandle = await window.showDirectoryPicker();
const files = [];
await walkDirectoryHandle(dirHandle, dirHandle.name, files);
return files;
} catch (err) {
// 用户点击取消:直接返回 null,不再弹出降级框
if (err && err.name === 'AbortError') {
return null;
}
// 如遇到 SecurityError(例如跨源 iframe 受限),继续向下执行降级方案
console.warn('showDirectoryPicker 不可用,切换至 webkitdirectory 降级方案:', err);
}
}
return pickByWebkitDirectory();
}
async function walkDirectoryHandle(dirHandle, parentPath, files) {
for await (const [name, handle] of dirHandle.entries()) {
const currentPath = `${parentPath}/${name}`;
if (handle.kind === 'file') {
const file = await handle.getFile();
files.push({ path: currentPath, file });
} else if (handle.kind === 'directory') {
await walkDirectoryHandle(handle, currentPath, files);
}
}
}
function pickByWebkitDirectory() {
return new Promise((resolve) => {
const input = document.createElement('input');
input.type = 'file';
input.multiple = true;
input.setAttribute('webkitdirectory', '');
input.setAttribute('directory', '');
input.style.display = 'none';
document.body.appendChild(input);
let settled = false;
const cleanup = () => {
input.remove();
window.removeEventListener('focus', handleFocusBack);
};
input.addEventListener('change', () => {
settled = true;
const list = Array.from(input.files || []).map((file) => ({
path: file.webkitRelativePath || file.name,
file,
}));
cleanup();
resolve(list);
});
// 当用户在文件对话框点取消时,窗口重新获得焦点,可用延时兜底清理 DOM
const handleFocusBack = () => {
setTimeout(() => {
if (!settled) {
settled = true;
cleanup();
resolve(null);
}
}, 300);
};
window.addEventListener('focus', handleFocusBack, { once: true });
input.click();
});
}
document.getElementById('selectFolderBtn').addEventListener('click', async () => {
const output = document.getElementById('output');
const files = await pickDirectoryFiles();
if (files === null) {
output.textContent = '已取消选择';
return;
}
output.textContent = files
.map((item) => `${item.path} (${item.file.size} bytes)`)
.join('\n');
});
</script>
关于写回本地文件的本质区别:降级方案(webkitdirectory 与 webkitGetAsEntry)只能提供只读的 File 对象。如果你的需求是把文件夹上传到服务器,或者在浏览器内存里解析、转换后打包成 ZIP 下载,降级方案完全胜任;但如果你的核心功能像本地代码编辑器那样“原地修改磁盘上的原文件并静默保存”,浏览器在没有 showDirectoryPicker 时没有等价替代接口,写回阶段必须改为触发文件下载或提示用户手动保存。
三种方案能力边界对照与常见问题
把三种方式放到一起对比,可以清楚看到各自负责的边界在哪里,避免在项目设计阶段做出不切实际的预期。
最后补充两个实际接入时常见的排错点:
- 不要一次性把几万个文件内容全读进内存:无论是
showDirectoryPicker还是webkitdirectory,拿到File对象时浏览器都只建立了句柄或元信息索引,文件字节还没有真正读入内存。只有在调用await file.text()、file.arrayBuffer()或上传时才会读取内容。如果用户选了一个包含node_modules的大目录,应该先根据path过滤掉不需要的目录,再分批读取或上传,否则页面标签页很容易卡死。 - 内网测试遇到
showDirectoryPicker失效先看地址栏协议:本地开发用http://localhost:3000正常,换用局域网 IPhttp://192.168.1.20:3000就走到了降级逻辑,这并不是浏览器突然不兼容,而是局域网 IP 的 HTTP 连接不被视为安全上下文。只要确认此时input[webkitdirectory]能正常接管,就说明降级链路已经工作到位。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。