VSCode悬浮预览图片需同时满足四个条件:路径为./开头的静态相对路径、插件已启用、workbench.hover.enabled、editor.hover.enabled和image-preview.enableHoverPreview均为true,且光标必须落在路径字符串的字母或数字内部。

VSCode 悬浮预览图像不是默认开箱即用的功能,必须同时满足路径格式、插件启用、设置开启和光标位置四个条件,缺一不可。
悬停预览不触发?先确认这三项设置为 true
内置 hover 机制依赖 VSCode 的通用悬停系统,Image Preview 插件在此基础上叠加图像渲染逻辑。以下三个配置必须同时为 true:
-
workbench.hover.enabled—— 控制整个工作台的悬停功能(包括文件资源管理器) -
editor.hover.enabled—— 控制编辑器内代码区域的悬停(如变量、函数提示) -
image-preview.enableHoverPreview—— Image Preview 插件自身的开关,独立于前两者
在设置界面搜索对应关键词即可勾选;若通过 settings.json 修改,请确保没有拼写错误或被其他扩展覆盖。
路径必须是静态相对路径,且以 ./ 或 ../ 开头
Image Preview 插件只解析可静态推断的字符串字面量,不执行 JS 表达式或变量拼接。以下写法全部无效:
-
assets/logo.png(缺./) -
require('./icon.svg')(含函数调用) -
https://example.com/photo.jpg(网络地址) -
data:image/png;base64,iVBOR...(Base64 字符串,除非插件明确声明支持)
正确写法仅限:./img/avatar.jpg、../public/logo.webp。路径中含中文或空格时,建议重命名避免潜在解析失败。
光标必须落在路径字符内部,且文件类型被支持
悬停生效有严格的位置要求:
- 光标需停在路径字符串的字母或数字上(例如
logo.png中的l或g),停在引号、括号、斜杠或空格上均不触发 - 默认支持
.md、.html、.css、.vue等文件类型;.js和.ts需手动添加语言支持:"image-preview.supportedLanguages": ["javascript", "typescript"] - 文件必须真实存在于当前工作区目录下,右键路径 →
Reveal in Explorer可快速验证
大图不显示?检查 image-preview.maxSize
插件默认限制预览文件大小(单位 KB),超限会静默跳过。常见现象是 5MB 的 PNG 悬停无反应。临时解决方法:
- 打开设置,搜索
image-preview.maxSize - 将其值调高,例如设为
10240(10MB) - 注意:过大图片可能拖慢响应,建议仅调试时调高
真正影响体验的往往是路径合法性与光标落点——这两个细节出错时,即使插件已安装、设置全开,也完全不会弹出任何提示,容易误判为插件失效。











