Readest iOS 封面选择器静默失效问题剖析PHPicker 回退、HEIC 过滤与 Tauri fs 作用域修复PR #5346【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest导读本文基于 Readest 项目中一次真实的 iOS 缺陷排查与修复记录PR #53462026-07-26 合并完整还原“更换封面图片”在 iOS 上静默失效点了没反应、什么都不发生的根因链条noFilter误用导致文件选择器类型错误、HEIC 图片被客户端白名单过滤、以及模拟器环境下$APPCACHE裸目录不在 Taurifs:scope内导致mkdir被拒。文章以该文档为主线结合仓库中 useFileSelector.ts、BookDetailEdit.tsx、bookService.ts、nativeAppService.ts 与 default.json 等源码逐层印证读完你将掌握 Tauri 文件选择器按平台/类型分支的设计模式、fs 作用域 glob 的坑点以及如何用“先复现、再定位、后修复、再回归”的方式排查这类“无报错无提示”的静默故障。背景一条只有 11 行的 bug 记录牵出三层缺陷原文档记录于项目的.claude/memory目录属于 AI 协作记忆文件用于沉淀一次已合并的修复MERGED #5346。它浓缩了三个相互独立又叠加出现的缺陷选择器类型错误iOS 上任何选择类型都强制noFilter isIOSApp导致空扩展名列表被tauri-plugin-dialog解析为空 UTTypes封面选择器最终打开的是“文件”AppUIDocumentPickerViewController而不是系统照片选择器PHPickerViewController甚至能列出.epub文件。HEIC 静默丢弃noFilter路径会重新应用客户端白名单png/jpg/jpeg/gif而 iPhone 相机默认的 HEIC 格式不在其中选中后files.length 0handleSelectLocalImage 直接提前返回——没有任何错误、toast 或提示。模拟器专属的 mkdir 失败getCachedImageUrl写入缓存目录时mkdir $APPCACHE本身被 Tauri 的fs:scope拦截forbidden path: ... allow-mkdir因为作用域里只有$APPCACHE/**/*缺少裸目录$APPCACHE真机因require_literal_separator: true语义被/private/var/mobile/Containers/Data/Application/**/*覆盖而模拟器容器路径~/Library/Developer/CoreSimulator/匹配不到。下面分别展开每一层并在源码中找到对应实现证据。第一层noFilter无条件开启iOS 选了错误的系统选择器缺陷根源一行看似无害的强制过滤原文档指出修复前 useFileSelector.ts 中的selectFileTauri对每一种选择类型都执行了noFilter appService?.isIOSApp。也就是说iOS 上无论是选书、选字体、选图片还是换封面一律传入空extensions列表。在 Tauri 侧空扩展名经tauri-plugin-dialog的parseFiltersOption([])处理后得不到任何 UTTypesfiltersIncludeImage判断为 false最终回退到UIDocumentPickerViewController文件 AppUTType.item兜底而不是PHPickerViewController照片选择器。原文档给出了一个很直观的验证结果iOS 封面选择器里竟然列出了.epub文件。对照 AndroidAndroid 分支传递的是真实扩展名如png/jpg/jpeg/gif因此能命中系统照片选择器行为一直正常。差异完全由平台对过滤参数的处理方式不同造成。修复方案按“类型”而非“平台”决定是否过滤修复后的逻辑useFileSelector.ts 中可见const isImageSelection options.type covers || options.type images; const noFilter (appService?.isIOSApp !isImageSelection) || (appService?.isAndroidApp (options.type books || options.type dictionaries || options.type audio || options.type generic)); const exts noFilter ? [] : options.extensions || [];iOS仅对非图片选择books / fonts / dictionaries / audio / generic 等使用无过滤选择器covers和images必须传扩展名让对话框插件打开 PhotosPHPicker界面与 Android 行为对齐。Android保留原有策略——SAF 按 MIME 过滤小众扩展名如 Moon Reader 的.mrexpt、有声书的.m4b没有注册 MIME 会置灰因此 books / dictionaries / audio / generic 依旧无过滤由客户端在选中后重新套用扩展名白名单这一点原文档的注释与源码hasAllowedExtension完全一致相关逻辑见 useFileSelector.ts 与第 151-172 行。一个有意的边界iOS 字体选择不启用过滤原文档特别强调刻意没有把 iOS 的fonts类型改成带过滤。原因是 woff/woff2 在 iOS 上可能缺少对应的 UTTypes一旦加了过滤字体文件在文件选择器里会被置灰greyed out反而无法选择。这是“过滤能力”与“实际可选择范围”之间的权衡——宁可多显示、不能错杀。第二层HEIC 被白名单静默丢弃“选中了但什么都没发生”缺陷机制当noFilter true时插件侧不做任何过滤但selectFileTauri会在客户端用options.extensions白名单重新筛选useFileSelector.ts。封面选择的预设扩展名是[png, jpg, jpeg, gif]FILE_SELECTION_PRESETS而HEIC 是 iPhone 相机的默认输出格式不在列表内。于是用户从照片选择器里挑了一张 HEIC 照片 → 白名单把它过滤掉 →files.length 0→ 调用方 handleSelectLocalImage 看到result.error || result.files.length 0直接returnconst handleSelectLocalImage async () { selectFiles({ type: covers, multiple: false }).then(async (result) { if (result.error || result.files.length 0) return; // ...实际处理封面文件 }); };整个过程没有任何错误分支、没有 toast、没有 UI 反馈——这就是“silent no-op”的字面含义用户点击“更换封面”、选好照片然后页面纹丝不动。与“无过滤导入书籍”提示机制的对比有意思的是源码里对这种“白名单静默丢弃”并非没有考虑在 useFileSelector.ts 中books 类型被丢弃的文件会弹出错误 toastif (options.type books kept.length files.length) { const skipped files.filter((file) !kept.includes(file)); const filenames skipped.map(({ name, path }) name || getFilename(path!)).join(, ); eventDispatcher.dispatch(toast, { type: error, message: _(Failed to import book(s): {{filenames}}, { filenames }), timeout: 5000, }); }代码注释明确解释了原因books 是唯一已经完成翻译的 toast 文案而对 audio / dictionary 选择来说这条消息语义不通。因此封面covers在此次修复之前恰好处于“既不显示 toast、也不走错误提示”的空白地带——这正是文档强调的“No error, no toast, nothing”。修复效果修复后 iOS 的covers/images走带过滤路径直接把 HEIC 等格式交给系统照片选择器PHPicker 本身支持 HEIC客户端白名单不再介入HEIC 得以正常选中并进入后续的缓存流程。第三层模拟器专属缺陷——$APPCACHE裸目录不在 fs 作用域内故障路径还原handleSelectLocalImage选中文件后会调用appService.getCachedImageUrl(filePath)把封面拷贝进缓存目录并返回可展示的 URL。完整调用链如下appService.ts 的getCachedImageUrl委托给BookSvc.getCachedImageUrlbookService.ts 中缓存 key 为img_${md5(pathOrUrl)}写入路径是${cachePrefix}/${cachedKey}const cachedKey img_${md5(pathOrUrl)}; const cachePrefix await ctx.fs.getPrefix(Cache); const cachedPath ${cachePrefix}/${cachedKey}; if (await ctx.fs.exists(cachedPath, None)) { return await ctx.fs.getImageURL(cachedPath); } else { const file await ctx.fs.openFile(pathOrUrl, None); await ctx.fs.writeFile(cachedKey, Cache, await file.arrayBuffer()); return await ctx.fs.getImageURL(cachedPath); }writeFile(cachedKey, Cache, ...)走 nativeAppService.ts 的ensureDirExists→createDir(, Cache)即对$APPCACHE本身执行 mkdir。问题就出在第 3 步Tauri 的fs:scope要求路径匹配作用域条目而当时作用域里只有$APPCACHE/**/*。原文档指出Tauri 使用require_literal_separator: true语义$APPCACHE/**/*需要至少一个子路径组件因此对$APPCACHE裸目录的allow-mkdir会被拒绝抛出forbidden path: ... allow-mkdir。为什么真机没事、模拟器必炸对比 default.json 中的fs:scope条目{ identifier: fs:scope, allow: [ { path: **/Readest }, { path: **/Readest/**/* }, { path: **/com.github.johnfactotum.Foliate/**/* }, { path: **/last-book-cover.png }, { path: $TEMP/**/* }, { path: $APPCACHE }, { path: $APPCACHE/**/* }, { path: /private/var/mobile/Containers/Data/Application/**/* } ] }真机iOS 应用容器位于/private/var/mobile/Containers/Data/Application/UUID/Library/Caches。条目/private/var/mobile/Containers/Data/Application/**/*在require_literal_separator: true语义下**可以跨越UUID/Library/Caches的多级目录*匹配最后的 bundle id 目录因此整个缓存目录树天然被覆盖mkdir $APPCACHE也合法。模拟器容器位于~/Library/Developer/CoreSimulator/...下与上述条目完全不匹配而$APPCACHE/**/*又因为require_literal_separator匹配不了裸目录本身。于是mkdir $APPCACHE直接触发allow-mkdir越权错误。修复为裸目录补一条作用域修复方式与现有**/Readest**/Readest/**/*成对声明的模式保持一致在fs:scope中新增裸目录$APPCACHE与已有的$APPCACHE/**/*组成“裸目录 递归子项”的完整覆盖即上面前置 JSON 中的{ path: $APPCACHE }。原文档同时留下了两个工程要点$TEMP存在同样的裸目录缺口但未被修复——因为目前没有任何代码路径会命中它属于“已知但未触发”的隐患值得后续关注。任何mkdir被拒的 rejection 都因为handleSelectLocalImage没有.catch而变成 unhandled promise rejection即使用户打开 Web Inspector 也只能在控制台看到 Promise 拒绝界面上毫无痕迹。回归测试佐证能力集的缓存作用域约束仓库中的测试 capability-external-cache-scope.test.ts 针对另一类缓存作用域问题Android 外部缓存$CACHEissue #4853验证了同族逻辑外部存储的scope-cache权限集自带$CACHEglob在部分设备上解析失败会导致 fs 能力构建失败、应用启动黑屏Readest 的解法是只授予fs:read-all/fs:write-all命令集加$APPCACHE作用域条目测试断言$APPCACHE/**/*仍在作用域内且命令覆盖完整。它从侧面印证了“fs 作用域条目必须是精确匹配的路径模式”这一整套约束的存在也说明了为什么$APPCACHE裸目录的缺失会真实阻断 mkdir。排查这类“静默失败”的通用方法论原文档在结尾给出了一个非常实用的运维建议值得提炼为可复用的排查清单先怀疑选择器任何“picker 点了没反应”的报告第一步都在 Safari Web Inspector 里看控制台——由于调用方缺少.catchTauri IPC 拒绝只会表现为 unhandled promise rejection界面上不会出现 toast 或错误弹窗。区分“选中为空”与“写入失败”files.length 0可能来自扩展名白名单过滤HEIC 案例也可能来自用户取消而 mkdir 失败属于第二种报错形式是forbidden path: ... allow-mkdir。核对 fs 作用域与 glob 语义**/*不等于裸目录本身凡是“目录根 递归子项”都要成对声明模拟器与真机的容器路径完全不同作用域条目必须同时覆盖二者或使用$APPCACHE这类符号路径。修复后做平台矩阵回归iOS 真机、iOS 模拟器、Android 各跑一遍“更换封面”分别验证选择器类型Photos vs Files、HEIC 支持、缓存写入三个维度。相关关联记忆与进一步阅读原文档属于 Readest 的.claude/memory项目记忆体系文中还交叉引用了两条关联记忆ios-sim-drive-via-dev-server-relay如何通过 dev-server 中继驱动 iOS 模拟器与cover-stale-inplace-mutation-memo封面原地更新的另一类过期刷新 bug。本文讨论的核心代码可在以下路径继续深挖useFileSelector.ts —— 平台/类型分支的文件选择器核心逻辑与FILE_SELECTION_PRESETS全部预设BookDetailEdit.tsx —— 封面更换的 UI 入口与无.catch的调用方式bookService.ts —— 封面图片的 MD5 缓存写入逻辑nativeAppService.ts ——ensureDirExists的 exists createDir 回退与目录存在性缓存default.json ——fs:scope的完整路径声明含$APPCACHE裸目录修复capability-external-cache-scope.test.ts —— 同类 fs 缓存作用域约束的回归测试。小结一次 iOS “更换封面无反应”的排查最终落到三处不同层级的缺陷选择器类型判定noFilter与选择类型错配、客户端扩展名白名单HEIC 被过滤、以及 Tauri fs 作用域配置裸目录 glob 缺口。三者的共同点是都在静默地失败——没有报错、没有提示只有用户感知上的“点了没反应”。PR #5346 的修复为选择器引入了“平台 × 选择类型”的二维分支为作用域补上了裸目录条目并刻意保留了对 iOS 字体选择的宽松处理。对任何在 Tauri 上做跨平台文件选择、图片导入或缓存写入的开发者而言这套“先查控制台、再查过滤、最后查作用域”的排查顺序以及“目录根 递归子项成对声明”的配置纪律都是可以直接复用的经验。【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考