ImagePaste 插件安装失败主因是仓库添加错误或网络受限，需手动添加正确GitHub仓库；Mac用户可用Homebrew跳过pngpaste依赖，Win/Linux需确保剪贴板支持图像读取；安装后需检查ImagePaste.py和Default.sublime-keymap是否存在；路径错乱多因中文/空格文件名导致，建议用英文命名；粘贴无效常因语法模式非Markdown，须手动设为Markdown；预览不显示是因浏览器拦截本地图片，需通过OmniMarkupPreviewer的HTTP服务访问。
ImagePaste 插件安装失败常见原因
多数人卡在“按 Ctrl+Shift+P → Package Control: Install Package 后搜不到 imagepaste”，根本不是插件不存在，而是仓库没加对或网络受限。
- 必须先手动添加仓库：
https://github.com/lukauskas/imagepaste（注意不是 fork 分支或旧地址） - Mac 用户若用 Homebrew 安装过
pngpaste，可跳过依赖检查；Windows/Linux 用户需确认系统剪贴板能读取图像（部分远程桌面或沙盒环境会拦截） - 如果安装后无反应，检查
Packages/ImagePaste/目录下是否存在ImagePaste.py和Default.sublime-keymap—— 缺任一文件即为安装不完整
粘贴后图片路径错乱或链接不显示
默认行为是按 Markdown 文件名建同名子目录（如 report.md → report/），但中文文件名、空格、特殊字符会导致路径解析失败，os.path 在 Windows 下尤其容易出错。
- 务必用英文命名你的
.md文件，例如api_design.md，而非接口设计.md - 想统一存到
images/目录？直接修改Packages/ImagePaste/ImagePaste.py中的get_filename()函数，把gitbook_dir赋值行替换成：gitbook_dir = os.path.join(os.path.dirname(dirname), "images") - 相对路径生成逻辑依赖
view.file_name()返回值，如果当前文件未保存（即临时 tab），插件会 fallback 到 Sublime 默认缓存路径，此时粘贴可能失败或写入隐藏位置
Ctrl+V 不触发图片保存，只插入纯文本
这不是插件坏了，而是 Sublime 当前语法模式没识别为 Markdown。ImagePaste 只在 text.html.markdown 或 text.md 作用域下生效。
- 打开一个
.md文件后，右下角状态栏应显示Markdown—— 若显示Plain text，点击它并选Markdown - 也可手动设置：菜单
View → Syntax → Markdown → Markdown - 检查
Preferences → Package Settings → ImagePaste → Settings – User，确认没有误设"disabled_scopes": ["text.plain"]类似限制
图片保存成功但预览不显示（配合 OmniMarkupPreviewer）
OmniMarkupPreviewer 默认不加载本地 file:// 图片，浏览器安全策略会拦截，和插件本身无关。
- 启动预览前，先执行命令：
OmniMarkupPreviewer: Preview in Browser（快捷键Cmd+Alt+O/Ctrl+Alt+O），它会起一个本地 HTTP 服务，把路径转为http://127.0.0.1:port/xxx.png - 若仍 404，请确认图片实际保存路径与 Markdown 中写的
完全一致 —— 注意大小写、斜杠方向（Windows 下写images\会被当成字符串字面量，必须用正斜杠） - 不要指望拖拽图片进编辑器触发粘贴；ImagePaste 只响应剪贴板图像（截图、复制网页图、复制文件资源管理器中的 PNG/JPG）
get_filename() 很快，但忘了切语法模式或用了中文文件名，就会花半小时查日志。别跳步骤。 
