如何解决Markdown Preview Enhanced预览不显示图片问题？

Question

在使用 Markdown Preview Enhanced 插件时，常遇到本地图片无法正常预览的问题。典型表现为：图片路径正确但预览界面显示为空白或“图像损坏”提示。该问题多因插件安全策略限制导致，默认阻止了本地文件路径（file://）的加载。解决方法为：在 VS Code 设置中搜索 "Markdown Preview Enhanced"，找到并启用 **"Allow Unsafe Protocols"** 选项，或在文档头部添加 YAML front-matter 配置 `allowUnsafeProtocols: true`。此外，建议使用相对路径引用图片，并确保路径区分大小写且无中文或空格。重启预览即可生效。

Answer 1

1. 问题现象与初步诊断

在使用 Markdown Preview Enhanced 插件时，许多开发者会遇到本地图片无法正常预览的问题。典型表现为：尽管图片路径正确、文件存在且可手动打开，但在预览界面中显示为空白或提示“图像损坏”。

• 常见错误提示包括：“Failed to load resource: net::ERR_FILE_NOT_FOUND”
• 浏览器控制台报错：Not allowed to load local resource: file://...
• 该问题通常出现在 Windows 和 macOS 系统中的 VS Code 编辑器内嵌预览中

这一行为并非插件 Bug，而是出于安全策略的默认限制——现代渲染引擎（如 Electron）禁止直接加载本地文件协议（file://），以防止潜在的跨域攻击和信息泄露。

2. 根本原因分析

Markdown Preview Enhanced 基于 Electron 构建预览环境，其底层采用 Chromium 渲染机制。Chromium 默认禁用对本地文件系统的直接访问，尤其是在非可信上下文中加载资源时。

因素	说明
Security Policy	Electron 的内容安全策略（CSP）阻止 file:// 协议加载
Protocol Restrictions	allowUnsafeProtocols 默认为 false，限制非 HTTP/HTTPS 资源
Path Resolution	绝对路径（如 C:\images\pic.png）易被解析失败；相对路径更稳定

此外，操作系统级别的路径大小写敏感性差异（Linux/Unix 区分大小写，Windows 不区分）也可能导致路径匹配失败。

3. 解决方案层级递进

针对此问题，可采取由浅入深的多种方式解决：

1. 启用允许不安全协议选项： 在 VS Code 设置中搜索 “Markdown Preview Enhanced”，找到 Allow Unsafe Protocols 并勾选启用。
2. 文档级配置（YAML Front-matter）： 在 Markdown 文件头部添加如下元数据：

   ---
   allowUnsafeProtocols: true
   ---
   ![](./images/example.png)
   

   此方法适用于需要精细控制单个文档行为的场景。
3. 统一使用相对路径： 推荐结构如下：
   • docs/intro.md
   • docs/images/photo.jpg
   引用时使用：![](images/photo.jpg)
4. 避免特殊字符路径： 不建议使用含中文、空格或特殊符号（如 #、%、&）的路径名，应替换为空白或连字符。

4. 高级调试技巧与流程图

对于复杂项目结构或多团队协作环境，建议结合开发工具进行深度排查。

graph TD A[图片未显示] --> B{检查路径是否正确} B -->|是| C[查看控制台错误] B -->|否| D[修正路径] C --> E[是否存在 file:// 加载失败?] E -->|是| F[启用 allowUnsafeProtocols] E -->|否| G[检查 MIME 类型或编码] F --> H[重启预览窗口] H --> I[验证是否生效] I --> J[成功显示图片]

通过上述流程可系统化定位问题根源，避免盲目修改配置。

5. 最佳实践建议

为提升团队协作效率与文档可移植性，推荐以下最佳实践：

• 始终使用相对路径引用本地资源
• 建立标准化目录结构（如 assets/, images/）
• 在 CI/CD 中加入路径校验脚本，防止断链
• 使用版本控制系统（Git）管理图片资产
• 考虑将高频使用的图片托管至内部静态服务器（如 Nginx 或 GitHub Pages）

例如，可通过本地 Web Server 提供图片服务，将引用改为 http://localhost:8080/images/pic.png，彻底规避 file 协议限制。