🖼️ 在 VuePress 项目里正确「粘贴图片」的方式（VS Code）

TL;DR

使用命令：Paste Image: Paste Image（macOS：Cmd+Alt+V）→ 保存到 docs/.vuepress/public/uploads/，并插入 ![](/uploads/xxx.png)。
不要用普通 拖拽 / Cmd+V 文件 → 会生成相对路径，构建时易触发 @source/... 报错。
构建前有 规范化与压缩脚本，能自动修复误用的相对路径并压缩图片（≤1200px）。

1) 安装扩展（一次性）

在 VS Code 扩展商店安装 Paste Image（作者 mushan）。

2) 工作区设置（Workspace Settings）

settings.json 就是 Workspace Settings 吗？
是的：在仓库根目录创建（或编辑）.vscode/settings.json，这就是 工作区设置（只对当前项目生效）。

✅ 推荐：用 `${projectRoot}`（相对工作区根）

前提：你以 仓库根目录 /Users/adamc/Projects/61dh 打开 VS Code。

{
  "pasteImage.path": "${projectRoot}/docs/.vuepress/public/uploads",
  "pasteImage.insertPattern": "![$TM_FILENAME_BASE](/uploads/${imageFileName})",
  "pasteImage.forceUnixStyleSeparator": true
}

若你只打开了 `docs/` 作为工作区

此时 ${projectRoot} 指向 .../61dh/docs，路径应改为：

{
  "pasteImage.path": "${projectRoot}/.vuepress/public/uploads",
  "pasteImage.insertPattern": "![$TM_FILENAME_BASE](/uploads/${imageFileName})",
  "pasteImage.forceUnixStyleSeparator": true
}

或使用绝对路径（不受工作区影响）

{
  "pasteImage.path": "/Users/adamc/Projects/61dh/docs/.vuepress/public/uploads",
  "pasteImage.insertPattern": "![$TM_FILENAME_BASE](/uploads/${imageFileName})",
  "pasteImage.forceUnixStyleSeparator": true
}

3) 快捷键（建议）

.vscode/keybindings.json

[
  { "key": "cmd+alt+v", "command": "pasteImage.pasteImage", "when": "editorTextFocus && editorLangId == markdown" }
]

4) 正确使用

截图 / 复制的图片像素 → 在 .md 中按 Cmd+Alt+V（或命令面板运行 Paste Image: Paste Image）。
已有文件 → 亦需运行 Paste Image: Paste Image 并选择文件（不要直接 Cmd+V 文件）。

插入后应看到：

![](/uploads/your-image.png)

5) 构建前自动规范与压缩

package.json

{
  "scripts": {
    "prebuild": "node scripts/normalize-md-images.mjs && node scripts/optimize-images.mjs && node scripts/optimize-svgs.mjs",
    "build": "vuepress build docs",
    "dev": "vuepress dev docs",
    "predev": "node scripts/normalize-md-images.mjs"
  }
}

normalize-md-images.mjs：把相对路径复制到 public/uploads/ 并改为 /uploads/...
optimize-images.mjs：sharp 等比缩放至 ≤1200px 并压缩（支持 .jpg/.jpeg/.png/.webp/.JPG/...）
optimize-svgs.mjs：svgo 精简 SVG

6) 快速排查

图片没入 uploads：检查 pasteImage.path 是否与工作区根匹配；查看 View → Output → “Paste Image” 日志的最终写入路径。
仍见 @source/... 报错：说明某些 Markdown 中仍是相对路径；直接运行 npm run dev/build，或手动改为 /uploads/...。

7) 允许的链接格式（唯一）

![](/uploads/filename.png)

$TM_FILENAME_BASE