QuickLook 视频预览黑屏或无声？按这份分级清单 10 分钟修好
【免费下载链接】QuickLookBring macOS “Quick Look” feature to Windows项目地址: https://gitcode.com/gh_mirrors/qu/QuickLook
QuickLook 视频预览出问题时别急着重装。QuickLook 是把 macOS「Quick Look」体验搬到 Windows 的开源工具：选中文件按一下空格，预览窗口立刻弹出，不用打开完整应用。但视频文件经常不给面子——黑屏、无声、窗口变形。好消息是，绝大多数 QuickLook 视频预览失败不是软件坏了，而是系统解码器没配齐，或者 QuickLook 插件没正常加载。本文给你一张症状对照表和一套按成本排好的修复路径。
预览本该长这样：
先对照症状，判断问题出在哪
下面这张表帮你 30 秒定位：症状对号入座，最可能的原因就在右边。
| 你看到的现象 | 最可能的原因 |
|---|---|
| 按下空格后窗口毫无反应，或直接闪退 | QuickLook.Plugin.VideoViewer 插件没加载成功，连探测阶段都没走到 |
| 能听到声音，画面区域一片黑 | 视频流用的编码（常见是 HEVC）系统里没有对应解码器，音频能解、视频解不了 |
| 窗口尺寸很小、拉伸变形 | MediaInfo 没解析出分辨率，窗口只能拿到默认尺寸 |
| 能播但一卡一卡 | 硬件加速与系统解码器不匹配 |
记住一个判断口诀：窗口压根不出来，多半是插件的事；窗口出来了但没画面，多半是解码器的事。
QuickLook 视频预览为什么会坏
先讲清原理，再动手，你才不会盲目试错。
QuickLook 用插件机制工作。视频预览由 QuickLook.Plugin/QuickLook.Plugin.VideoViewer/ 目录下的插件负责，核心逻辑在 Plugin.cs。它先用 MediaInfo 库探测文件：能读出视频或音频流，才承认自己能处理这个文件。所以插件没加载、或 MediaInfo 没工作，窗口自然不出来。
真正干活的是系统解码器。QuickLook 本身不解码视频，画面全靠系统那套解码组件。H.264/MPEG-4 依赖 Windows Media Player 相关组件，HEVC 则是微软商店单独售卖的扩展，MKV 容器里的 DTS 音频还需要第三方解码器包。哪一环缺了，就坏在哪一环。
容器和编码是两回事。同样是 .mp4，里面可能装 H.264，也可能装 HEVC；扩展名不能代表内容。所以诊断时别盯文件后缀，要看里面到底是什么编码。
按投入成本分级修复：能不动代码就不动
这一节把修复手段按你付出的成本从低到高排好，从上一档没修好再往下走。
零操作档：5 分钟内的三件事
- 打开 QuickLook 设置，到「插件」选项卡确认「视频查看器」处于启用状态。
- 清空缓存：删掉
%APPDATA%\QuickLook\Cache目录下的所有文件。 - 彻底重启：任务栏右键 QuickLook 图标选择「退出」，再重新启动。
这三步能过滤掉一批「偶发坏掉」的情况，成本几乎为零。
解码器档：解码器到底怎么装才对
「有声无画面」大多停在这一档。对着编码找方案：
| 编码 / 组合 | 对应的安装方案 |
|---|---|
| H.264 / MPEG-4 | 确认 Windows Media Player 相关组件完整，然后运行sfc /scannow系统文件检查器 |
| HEVC / H.265 | 微软商店安装「HEVC 视频扩展」，或装第三方 HEVC 解码器包 |
| MKV 容器 + DTS 音频 | 安装 LAV Filters 解码器包，并在 QuickLook 设置里启用「使用系统解码器」选项 |
⚠️ 拿不准是哪个编码在作祟时，可以先用 QuickLook.Plugin.ThumbnailViewer 插件看看能不能出缩略图，出得来基本就说明视频流本身没坏，问题集中在解码环节。
进阶档：改参数前先把备份放在心里
走到这一步意味着前两档都无效，需要碰配置了。
- 插件优先级：在 Plugin.cs 里，
Priority当前是-3。多个插件抢同一个文件时，优先级高者胜出；把它调成10，QuickLook 插件就有机会压过别的插件。 - 媒体信息解析：给 MediaInfo 的初始化代码补充完整解析选项，诊断信息更全，黑屏这类模糊问题更容易定位。
修好之后：把预览窗口调舒服
问题修完，顺手做两个体验增强。
窗口尺寸：修改 ViewerPanel.xaml 里的控件属性，把<UserControl>的MinWidth设为800、MinHeight设为600，不同分辨率下都不会挤成一团。
快捷键：在 ViewerPanel.xaml.cs 里加键盘支持——空格播放/暂停，右箭头快进 10 秒，左箭头快退 10 秒，ESC 关闭窗口。预览时手不离键盘，效率高一截。
60 秒体检：一张表确认没漏项
修复前后各扫一遍这张表，确保 QuickLook 视频预览功能状态在线。
| 检查项 | 确认方式 |
|---|---|
| 必要解码器已装 | 对照上面解码器表逐项核对 |
| 视频查看器插件已启用 | 设置 → 插件 选项卡 |
| 文件编码在支持范围 | 用 MediaInfo 看一眼实际编码 |
| 缓存已清理 | %APPDATA%\QuickLook\Cache清空过 |
| 插件优先级设置过 | 改过Priority并重启生效 |
| 多种分辨率都测过 | 挑 720p / 1080p 各一个文件试 |
还解决不了？进源码层调试
走到这里说明问题比较刁钻，直接进代码里看。
先克隆仓库：
git clone https://gitcode.com/gh_mirrors/qu/QuickLook然后用 Visual Studio 打开 QuickLook.slnx，把 QuickLook.Plugin.VideoViewer 设为启动项目，在 Plugin.cs 的 CanHandle 方法打断点，把那个坏视频拖进去，一步步看是哪个判断把文件挡在了外面。
QuickLook 视频预览的坑，九成落在解码器和插件加载这两处，按上面的成本分级走下来基本都能落地。把系统解码器保持更新、QuickLook 版本和插件同步更新，是省事的长期方案。另外提醒一句：别同时启用多个视频相关插件，容易互相打架产生冲突。
【免费下载链接】QuickLookBring macOS “Quick Look” feature to Windows项目地址: https://gitcode.com/gh_mirrors/qu/QuickLook
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
