Windows 不显示 HEIC 缩略图不是解码问题是接口问题【免费下载链接】windows-heic-thumbnailsEnable Windows Explorer to display thumbnails for HEIC/HEIF files项目地址: https://gitcode.com/gh_mirrors/wi/windows-heic-thumbnails你的 iPhone 照片导进 Windows 后资源管理器里全是一排灰色方块——这就是许多人第一次遇见 HEIC 的瞬间。windows-heic-thumbnails 是一个专门解决这个问题的开源插件它让 Windows 10/11 的资源管理器原生显示 HEIC/HEIF 缩略图装好只要三分钟。如果你只想赶紧让照片露脸可以直接跳到下一节如果你还想搞懂资源管理器到底在等什么这篇文章会把你带到比安装界面深得多的地方。三分钟装好先看到结果再谈原理安装不需要编译任何代码也不需要反复折腾系统设置。步骤只有三步确认已安装最新版 Microsoft Visual C Redistributablex64大部分 Windows 10 机器自带把发布包里的HEICThumbnailHandler.dll、heif.dll、libde265.dll三个文件解压到同一个文件夹在该文件夹打开命令行运行regsvr32 HEICThumbnailHandler.dll。然后刷新资源管理器窗口——不需要重启不需要注销。灰色方块会变成真实照片的预览图这个变化几乎是即时的。好奇登记这一步到底做了什么regsvr32会调用 DLL 内部的DllRegisterServer函数它往注册表写了几条记录把你的处理程序挂到.heic扩展名的缩略图提供程序插槽上。值得注意的两个细节注册信息写在当前用户分支HKEY_CURRENT_USER下不需要动系统级配置它只碰这一个插槽不修改文件关联、不接管双击打开、不装常驻进程。卸载同样是一条命令regsvr32 /u HEICThumbnailHandler.dll它会把写过的注册表项清干净。反转一资源管理器要的不是能打开文件的软件很多人给 HEIC 装了一堆全能看图软件缩略图依然缺失于是怪系统、怪文件。其实资源管理器的逻辑很简单它从不关心谁能打开这个文件它只问谁能给我生成一张小图。当资源管理器扫描一个文件夹时系统会为每种文件类型查找对应的缩略图提供程序Thumbnail Provider。找不到就画一个通用图标——这正是灰色方块的来源找到了就把文件交给它等它交回一张位图。这套对话协议建立在 COM微软的组件对象模型之上。一个缩略图提供程序本质上是实现了一组接口的 DLLIThumbnailProvider::GetThumbnail()负责按指定尺寸给一张位图IInitializeWithStream负责把文件以流的形式递进来。windows-heic-thumbnails 的核心类CHEICThumbProvider同时实现这两个接口一进一出整个缩略图生命周期就此闭环。这里有个普通用户不会注意、但恰恰体现工程素养的细节插件选择的是IInitializeWithStream流式初始化而不是更省事的按文件路径初始化。源码注释写得很直白——这是为了能被隔离进程承载。意味着浏览照片时缩略图生成可能发生在独立进程里即使某个损坏文件把解码器弄崩资源管理器本体也毫发无损。对这类寄生在系统里的插件来说稳定性是最重要的隐性指标。反转二最快的解码是不解码多数人以为显示 HEIC 缩略图等于把整张照片完整解码一遍。如果真是这样这个插件就不该这么轻巧了。HEICHEIF 的苹果实现文件有个体贴的设计文件内部常常自带一张低分辨率预览图相当于书的封面页。GetThumbnail的第一件事就是问 libheif这个文件里有没有内嵌缩略图如果有直接拿它当底稿全程不碰全尺寸像素。// 关键路径先查文件是否自带缩略图HEIF 规范中的封面 heif_item_id thumbnail_ID; int nThumbnails heif_image_handle_get_list_of_thumbnail_IDs(image_handle, thumbnail_ID, 1); if (nThumbnails 0) { // 有内嵌缩略图 → 用缩略图句柄替换主图句柄跳过全图解码 struct heif_image_handle* thumbnail_handle; err heif_image_handle_get_thumbnail(image_handle, thumbnail_ID, thumbnail_handle); image_handle thumbnail_handle; }只有当文件没有内嵌缩略图时代码才走完整解码分支而且依然精打细算按需缩放只有图片尺寸超过请求的大小时才调用heif_image_scale_image避免多余的像素搬运HDR 兜底解码选项里convert_hdr_to_8bit true把 iPhone 上常见的 10 位色深照片安全降到 8 位显示不会出现灰蒙蒙一片一次像素搬运libheif 输出 BGRA 颜色顺序而 Windows 位图要求 ARGBCreateDIBFromData用一个循环完成通道重排直接写入内存位图。这套先封面、后全图、必要时缩放的策略让缩略图生成在绝大多数情况下只是解一张巴掌大的预览图而不是一张 4000 万像素的原片。这才是它在上千张照片的文件夹里滚动不卡顿的真正原因。三个文件一场分工明确的接力安装包里只有三个 DLL职责边界极其清晰文件角色一句话解释HEICThumbnailHandler.dll主插件实现 COM 接口与资源管理器对话负责缩放与位图生成heif.dll容器解析libheif 运行时读懂 HEIF/HEIC 容器结构主图、缩略图、元数据libde265.dll编解码内核真正解 H.265/HEVC 像素流的部分把它和另一种常见思路对比你会更清楚只做一件事的价值。微软商店里其实有一款官方 HEIF 扩展但要付费或看广告且依赖系统自带的 WIC 图像管线而 windows-heic-thumbnails 是开源的三个文件复制到任意文件夹就能用方案成本是否开源需要管理员缩略图效果微软商店 HEIF 扩展付费/含广告否否好本项目libheif COM免费是否仅当前用户注册好自行实现 HEVC 解码开发成本极高——不现实把解码交给久经考验的 libheif而不是从零写 HEVC 解码器是项目最务实的技术决策。libheif 是开源社区广泛使用的 HEIF 参考实现支持 10 位色深、透明通道、多图容器等完整特性内存管理与错误处理都经过大量项目打磨。插件只做自己擅长的事翻译 Windows 的接口请求。给构建者一个 5MB 的减法决策如果你打算自己编译项目根目录的vcpkg-overlay/藏着一个很能体现设计态度的细节。libheif 默认会连带编译 x265——一个 H.265编码器。但缩略图插件只需要解码编码器永远是死代码。于是项目提供了一个 vcpkg overlay 端口见vcpkg-overlay/libheif/portfile.cmake编译时显式关掉WITH_X265、WITH_DAV1D、WITH_EXAMPLESvcpkg_cmake_configure( SOURCE_PATH ${SOURCE_PATH} OPTIONS -DWITH_EXAMPLESOFF -DWITH_DAV1DOFF -DWITH_X265OFF )项目文档里算过这笔账砍掉 x265 能省下一个约 5MB、永远不会被调用的 DLL。对以小而稳为卖点的插件来说这 5MB 不只是体积更是攻击面与分发负担的减少。如果你也做 Windows 原生扩展这个思路值得抄走按使用场景裁剪依赖比堆更多功能更能体现工程成熟度。装完还不出图五步排查清单多数问题不是插件坏了而是环境或缓存没跟上。按顺序排查确认系统是 64 位 Windows 10/11。项目明确要求 64 位32 位系统直接放弃三个 DLL 必须在同一目录。heif.dll和libde265.dll是运行时按文件名加载的拆开放会让主 DLL 找不到依赖老照片仍显示空白清缓存。注册时插件会调用SHChangeNotify通知系统作废缩略图缓存但 explorer 的缓存偶尔恋旧手动清理缩略图缓存即可怀疑某个文件解码出错开日志。插件内置分级日志在注册表HKCU\Software\Classes\CLSID\{2c93d534-2a1f-40d2-a375-babc92996987}下新建 DWORD 值LogLevel并设为 5TRACE日志会写入%LOCALAPPDATA%\HEICThumbProvider.log解码成功/失败、尺寸缩放、内存分配全部记录在案这是官方调试通道提示缺少 MSVCP140.dll 一类错误→ 说明 Visual C 运行库缺失补装 x64 版本即可。名词速查表HEIC / HEIF新一代图片格式。HEIF 是容器规范HEIC 是苹果的默认实现基于 H.265/HEVC 压缩同等画质下体积约为 JPEG 的一半COM微软的组件对象模型Windows 各子系统之间插拔式协作的标准协议Thumbnail Provider缩略图提供程序Windows 定义的接口资源管理器靠它向第三方代码索要文件缩略图IThumbnailProvider / IInitializeWithStream前者负责给一张指定尺寸的位图后者负责把文件以流的方式交给你Shell 扩展向 Windows 资源管理器注入功能的一类插件统称libheif开源的 HEIF/HEIC 解析与解码库本项目的解码核心libde265开源的 H.265/HEVC 解码器libheif 的底层引擎regsvr32Windows 自带的 COM 组件注册工具本质是调用 DLL 的注册/注销函数vcpkg微软的 C/C 依赖管理工具本项目用它安装并裁剪 libheif。下一步别停留在读完普通用户现在就可以动手把三个文件解压到固定文件夹跑一次regsvr32然后打开 iPhone 照片文件夹刷新——十秒钟就能验证这篇文章的全部结论。开发者如果想看完整机制直接读源码src/HEICThumbnailHandler.cpp的GetThumbnail是整条管线的核心src/dllmain.cpp展示了一个 COM DLL 从注册、注销到类工厂的全流程src/log.cpp的分级日志设计则是可以复用的调试范式。想自己编译按 README 装好 libheif记得用 overlay 端口省下那个 5MB 的 x265。这个插件证明了一件事解决一个痛点不一定要造一个庞大的软件把正确的接口接对往往就够了。下次当你看到资源管理器里某种文件类型集体失声可以先问一句它的缩略图提供程序装了吗【免费下载链接】windows-heic-thumbnailsEnable Windows Explorer to display thumbnails for HEIC/HEIF files项目地址: https://gitcode.com/gh_mirrors/wi/windows-heic-thumbnails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考