Electron 应用给自定义文件格式做 Windows 缩略图预览

桌面应用一旦有了自己的文件格式，用户很快就会提一个需求：能不能在资源管理器里直接看到文件长什么样，而不是一排一模一样的图标。

这件事在 Electron 里没有现成 API。nativeImage 只负责应用自己的托盘、窗口图标，管不到资源管理器怎么渲染文件。资源管理器的缩略图由 Windows Shell 扩展提供，是一个必须用 C++ 实现的 COM 组件，和 Electron 的 JavaScript 世界完全不在一层。

下面用一个虚构的 .proj 格式走完整个流程。整件事分成三块：文件格式要能被快速读取、要有一个 Shell 扩展 DLL、这个 DLL 要正确注册进系统。三块都对了才有预览图，任意一块出错的表现完全一样——继续显示图标。这一点让排查过程比预想的长。

下面这张图先给出整体结构。它不是业务流程图，而是运行时边界图：Electron 侧只负责写文件，Shell 扩展是独立的原生 DLL，资源管理器通过注册表找到它。

文件格式要为"只读缩略图"留一条快路

先说格式设计，因为它决定了后面能不能做得快。

自定义格式常见做法是直接用 ZIP 打包，工程数据、资源、元信息都塞进去。这种格式做缩略图会很难受：资源管理器为了显示一个图标，得解压整个工程，几十 MB 的文件也要全读一遍。

所以格式改成了外层容器：定长文件头 + 缩略图 PNG + 压缩负载。

[0..8)    magic          固定标识
[8..10)   version        容器版本
[10]      compression    压缩算法
[11..12)  reserved       保留位
[12..16)  thumbnailLen   缩略图长度
[16..20)  payloadLen     压缩负载长度
[20..32)  reserved       保留位
[32..]    PNG + 压缩负载

关键是 PNG 放在压缩负载之前。Shell 扩展只需要读定长头拿到长度，再顺序读出 PNG 就能返回，完全不碰后面的压缩数据，也不需要在扩展里引入解压库。

这一步的取舍是格式复杂度换取读取速度。多了一层容器，写入端要多维护一段头部逻辑，但缩略图路径从"解压整个工程"变成"读几十 KB"。

Shell 扩展要实现两个接口

缩略图扩展的本体是一个导出 COM 类工厂的 DLL。它要实现两个接口：

IInitializeWithStream：接收资源管理器给的文件流；
IThumbnailProvider：返回 HBITMAP。

IInitializeWithStream 比 IInitializeWithFile 更合适。前者拿到的是流，Shell 可以在沙箱里限制访问，扩展也不需要自己处理路径和文件锁。

GetThumbnail 的实现顺序就是格式设计的镜像：读头、校验、读 PNG、交给 WIC 解码、转成 HBITMAP。

// 先读定长头，magic 和版本不对就直接放弃
BYTE header[HEADER_SIZE] = {};
if (FAILED(ReadExact(stream_, header, HEADER_SIZE))) return E_FAIL;
if (!HasMagic(header, MAGIC, sizeof(MAGIC))) return E_FAIL;

const DWORD thumbnailLength = ReadUInt32LE(header + 12);
const DWORD payloadLength = ReadUInt32LE(header + 16);

// 长度字段必须和实际文件大小吻合，拒绝截断或伪造的容器
STATSTG statistics = {};
if (FAILED(stream_->Stat(&statistics, STATFLAG_NONAME))) return E_FAIL;
if (statistics.cbSize.QuadPart != HEADER_SIZE + thumbnailLength + payloadLength) return E_FAIL;

这里有个容易忽略的点：Shell 扩展加载在资源管理器进程里，输入是完全不可信的。用户可能双击任何一个改了后缀的文件。所以尺寸、长度、签名都要硬校验，PNG 尺寸也限定死，不符合就返回 E_FAIL 让 Shell 回退到图标，不要试图"尽力渲染"。

DLL 只导出 DllGetClassObject 和 DllCanUnloadNow，不导出 DllRegisterServer。这意味着不能用 regsvr32 注册，必须由安装器直接写注册表。

注册表位置决定了成败

DLL 编译出来、打进安装包、注册表也写了，缩略图仍然没有出现。

排查到这一步值得记下方法。直接用 CoCreateInstance 实例化 DLL 走完整流程，全程返回 S_OK，位图也能拿到——DLL 是好的。但资源管理器就是不显示。

这说明要测的不是 DLL，而是 Shell 自己那条取缩略图的路径。它有确定的入口：

// [1] Shell 能否把文件绑定到缩略图处理器
IThumbnailProvider* bound = nullptr;
hr = item->BindToHandler(nullptr, BHID_ThumbnailHandler, IID_PPV_ARGS(&bound));

// [2] 资源管理器实际使用的入口，THUMBNAILONLY 禁止回退到图标
IShellItemImageFactory* factory = nullptr;
item->QueryInterface(IID_PPV_ARGS(&factory));
factory->GetImage(size, SIIGBF_THUMBNAILONLY, &bitmap);

SIIGBF_THUMBNAILONLY 是这里的关键。不加这个标志，取不到缩略图时 Shell 会静默回退到图标并返回 S_OK，看起来一切正常。加上之后，失败会如实报出来。

结果很干脆：两个调用都返回 0x80040154，也就是 REGDB_E_CLASSNOTREG，类未注册。

原因是注册写在了 HKEY_CURRENT_USER。Shell 解析缩略图处理器时不认 HKCU 下的 CLSID 注册，必须写 HKLM。同一个 DLL、同一个文件、代码一行未改，把注册补到 HKLM 后两个调用立刻变成 S_OK 并产出 256×256 位图。

下面这张图把诊断结果整理出来，左右两侧唯一的差别就是注册表位置。

排查过程中还有两个方向被证明是错的，一并记下来避免重复踩：

怀疑进程隔离。官方文档提到缩略图处理器默认跑在独立进程，可以用 DisableProcessIsolation 关掉。设了之后没有任何变化——问题不是隔离，是类根本查不到。
怀疑缺 MSVC 运行时。dumpbin /dependents 显示 DLL 只依赖 ole32、GDI32、KERNEL32，是自包含的。

注册要写在 ProgID 上

注册位置之外还有一个层级问题。

资源管理器解析缩略图的顺序是：扩展名 → ProgID → ShellEx。如果只在扩展名下注册，而 ProgID 下有 DefaultIcon，那么 ProgID 这一层就先命中图标，扩展名下的注册没有机会生效。

所以两处都要写：

; CLSID 指向 DLL，Shell 扩展必须声明 Apartment
WriteRegStr HKLM "Software\Classes\CLSID\${CLSID}\InprocServer32" "" "$INSTDIR\resources\shell\Provider.dll"
WriteRegStr HKLM "Software\Classes\CLSID\${CLSID}\InprocServer32" "ThreadingModel" "Apartment"

; ProgID 和扩展名两处都注册，缺 ProgID 会被 DefaultIcon 抢先
WriteRegStr HKLM "Software\Classes\${PROGID}\ShellEx\${THUMB_IID}" "" "${CLSID}"
WriteRegStr HKLM "Software\Classes\.proj\ShellEx\${THUMB_IID}" "" "${CLSID}"

; 通知资源管理器关联已变化，否则缓存的图标不会刷新
System::Call 'shell32::SHChangeNotify(i 0x08000000, i 0, i 0, i 0)'

ThreadingModel 必须是 Apartment，资源管理器在 STA 中调用缩略图接口。

卸载要把这些项删干净。残留的 InprocServer32 会让资源管理器反复尝试加载一个已经不存在的 DLL。

写 HKLM 就得提权

既然注册必须进 HKLM，安装器就必须有管理员权限。

electron-builder 的 NSIS 目标里，perMachine: false 时 HKLM 能不能写取决于用户在安装向导里选了"仅为我安装"还是"为所有用户安装"。这会让缩略图时有时无——同一个安装包，两个用户装出来的行为不一样。

结论是把它设成 perMachine: true，安装器始终提权。

nsis: {
  include: 'build/thumbnail.nsh',
  oneClick: false,
  // 缩略图提供器必须注册到 HKLM，perMachine 让安装器始终提权
  perMachine: true,
}

这不是没有代价的：安装时必定弹 UAC，应用变成全机器安装，自动更新也会需要提权。Shell 集成本质上是机器级的能力，想要它稳定生效就得接受这个前提。

如果缩略图只是"有更好"的加分项，也可以保留 perMachine: false，在注册失败时跳过并在安装日志里提示，不中断安装。两种取舍都成立，取决于这个功能对产品的分量。

缓存会掩盖修复效果

最后一个实践细节。资源管理器会把"这个文件没有缩略图"的结论缓存在磁盘上，重启资源管理器不清理它。

改完注册后如果没看到变化，先删缓存再重启：

Stop-Process -Name explorer -Force
Remove-Item "$env:LOCALAPPDATA\Microsoft\Windows\Explorer\thumbcache_*.db" -Force
Start-Process explorer.exe

否则很容易把"缓存没刷新"误判成"修复没生效"，排查时会为此多绕一轮。

小结

给 Electron 应用做自定义格式的缩略图，难点不在写那段 C++，而在三处边界：文件格式要为只读快路留出位置，原生 DLL 无法交叉编译只能预编译分发，注册必须落在 HKLM 的 ProgID 上并因此牵出提权决策。

这类问题的共同特征是失败表现完全一样——都是继续显示图标。所以排查不能靠猜，要找到系统自己那条链路的入口，用 SIIGBF_THUMBNAILONLY 这样的标志把静默回退关掉，让失败如实报出来。