VSCode搭建最强Markdown编辑环境

1. 本文目标
2. 准备工作
3. 安装插件
4. 插件的用法

VSCode是笔者用过的最好用的开发工具，没有之一。笔者14年的码龄生涯中，先后用过Eclipse、 IntelliJ IDEA、 WebStorm、 PyCharm、 Visual Studio(2010/2013/2015)、 NetBeans、 Sublime Text等，但自从用VSCode之后，就再没换过其他工具，一直用到现在有5年多的时间。

1. 本文目标

这篇文章主要介绍如何使用VSCode来进行Markdown的写作，用VSCode来搭建一套markdown的文档写作环境。

什么是markdown？

Markdown是一种轻量级的标记语言，旨在简化文本格式化的过程。它允许用户使用纯文本格式编写文档，并通过简单的标记语法来添加格式，如标题、列表、粗体、斜体、链接和图片等。Markdown文件通常以.md或.markdown为扩展名。具体语法参见以下文档，这里不再赘述。

先展示一下最终的效果图：

2. 准备工作

官网下载VSCode并安装： https://code.visualstudio.com/

3. 安装插件

vscode默认是支持Markdown的，基本的语法、编辑功能、预览功能都可以用，但如果需要更高级的功能，可以安装一些插件来提升效率。使我们的markdown文档编辑起来更加丝滑、高效。

插件名称	发布者	功能介绍
Markdown All in One	Yu Zhang	支持快捷键（如粗体/斜体）、创建目录、表格自动格式化、LaTeX 数学公式支持等功能
markdownlint	David Anson	Markdown语法检查器，可识别和快速修复常见的Markdown语法错误。
Markdown Table	Takumi Ishii	Markdown表格编辑的神器，可对表格进格式化、插入行、行/列等。
Markdown PDF	yzane	支持将Markdown文件转换成pdf, html, png, jpeg等格式。
Markdown Preview Github Styling	Matt Bierner	Github使用的Markdown渲染样式，整体样式：朴素、简洁。
Markdown Preview Enhanced	Yiyi Wang	Markdown预览插件，支持目录树，提供更丰富的功能和更强的定制化能力。与`Markdown Preview Github Styling`是同类型的插件，可以根据自己的喜好选择其中一个安装。
Write Timestamp	michael gieson	插入系统当前时间戳，可以自定义格式。
Paste Image	mushan	粘贴图片，支持将剪切板里的图片直接保存到文档中。支持自定义保存路径。

4. 插件的用法

4.1. Markdown All in One

4.1.1. 快捷键

快捷键	功能
Ctrl + B	加粗
Ctrl + I	斜体
Ctrl / Cmd + Shift + V	切换预览模式和编辑模式

4.1.2. 创建/更新目录

打开命令面板（Ctrl + Shift + P）。
输入“Markdown All in One: Create Table of Contents”创建目录，输入“Markdown All in One: Update Table of Contents”更新目录。
点击/或按下回车确认。

4.1.3. 给标题增加序号

打开命令面板（Ctrl + Shift + P）
输入“Markdown All in One: Add/Update section Number”
点击/或按下回车确认

4.2. markdownlint

4.2.1. 格式检查

markdownlint安装后，默认会开启格式检查的功能。当markdown文档格式错误时，编辑器内对应的错误行会有（黄色波浪线的）提示信息。

4.2.2. 文档格式化

可以通过markdownlint对整个markdown文档进行格式化，并自动修复错误。

快捷键：

MacOS: Option + Shift + F Windows: Ctrl + Shift + F

鼠标右键：

编辑器内右键鼠标 -> 选择“Format Document With” -> 选择“markdownlint” -> 点击/或按下回车确认。
编辑器内右键鼠标 -> 选择“Format Document With” -> 选择“Configure Default Formatter...” -> 配置默认的格式化器。

保持时自动格式化：

settings.json文件中添加以下内容：

"editor.formatOnSave": true,
"editor.formatOnSaveMode": "modificationsIfAvailable"

4.3. Markdown Table

4.3.1. 格式化表格

打开命令面板（Ctrl + Shift + P），或者鼠标右键点击表格区域。
选择“Markdown Table: format table”。
点击/或按下回车确认。

4.3.2. 插入表格列

打开命令面板（Ctrl + Shift + P），或者鼠标右键点击表格区域。
选择“Markdown Table: insert column left/right”。
点击/或按下回车确认。

4.4. Markdown PDF

打开命令面板（Ctrl + Shift + P）。
输入“Markdown PDF:”。
选择需要导出的文件格式。
点击/或按下回车确认。

注意： Markdown PDF导出的PDF文件没有目录，如果需要目录，可以使用prince工具。prince的安装和使用可以参考《将Markdown转换为PDF文件(支持目录大纲)》。

4.5. Write Timestamp

快捷键

PC: ctrl-shift-t

MAC: cmd-shift-t

自定义时间格式

在settings.json文件中添加以下配置：

"writeTimestamp.bCustomFormat": "yyyy-mm-dd  HH:MM:SS"

4.6. Paste Image

默认快捷键:

Windows/Linux: Ctrl+Alt+V

MacOS: Cmd+Alt+V

自定义保存路径:

在settings.json文件中添加以下配置：

// 设置图片保存路径：与文件同级的目录创建一个与文件同名的文件夹，在此文件夹下存放图片。
"pasteImage.path": "${currentFileNameWithoutExt}/",
// 设置图片默认名称, 默认为当前文件名
"pasteImage.defaultName": "${currentFileNameWithoutExt}",

4.6.1. WSL环境下无法粘贴Windows剪贴板的图片

问题现象：

在Windows上用VSCode通过WSL Remote连接到WSL中编辑Markdown时，按Ctrl+Alt+V粘贴在Windows主机上复制的图片会失败，通常报错：There is not an image in clipboard.。

原因：

Paste Image插件运行在WSL（Linux）端的vscode-server里，读取剪贴板时调用的是Linux下的xclip，而xclip无法访问Windows主机的剪贴板（即使开启了WSLg，图片这种二进制剪贴板格式也无法跨过去）。所以本质不是插件Bug，而是Remote架构限制。

解决方案：

推荐二选一，按需要选择。

方案A（推荐）：使用 VSCode 内置的 Markdown 图片粘贴功能

VSCode 1.79+ 已经原生支持往Markdown里粘贴剪贴板里的图片，并且走的是VSCode自己的Remote协议，可以正确地把Windows主机剪贴板里的图片传到WSL再落盘，无需任何额外插件。

在settings.json里加入以下配置：

// 启用粘贴图片时自动复制为文件
"editor.experimental.pasteActions.enabled": true,
// 设置图片保存路径：与当前文件同级、与文件同名的目录下
"markdown.copyFiles.destination": {
    "**/*.md": "${documentBaseName}/"
},
// 粘贴时直接生成 Markdown 链接
"markdown.editor.filePaste.copyIntoWorkspace": "mediaFiles"

之后在Markdown文件中直接按 Ctrl+V（注意不是 Ctrl+Alt+V）即可粘贴图片，VSCode会自动保存图片到指定目录并插入![](xxx.png)链接。

方案B：改用 Markdown Image Paste for Remote 插件

mushan发布的Paste Image插件已多年未更新，对Remote场景没做适配。社区有专门面向Remote/WSL环境的替代插件 Markdown Image Paste for Remote（发布者 watahani），它通过WebView的clipboard API绕开了Linux端拿不到Windows剪贴板图片的问题。

安装后，使用方式与Paste Image基本一致，路径模板配置项为markdownImagePaste.path，例如：

"markdownImagePaste.path": "${currentFileNameWithoutExt}/",
"markdownImagePaste.defaultName": "Y-MM-DD-HH-mm-ss"

方案C（保留 Paste Image，推荐重度依赖路径模板的用户）：用 PowerShell 桥接 Windows 剪贴板

如果你已经习惯了Paste Image的pasteImage.path / pasteImage.insertPattern等路径模板，不想换插件，可以做一个xclip包装脚本，让Paste Image在 WSL 中调用xclip时实际去读取 Windows 主机的剪贴板。

原理

Paste Image在 Linux 端的实现是 spawn 一个 sh 脚本，本质上跑的是：

xclip -selection clipboard -t image/png -o > /tmp/xxx.png

我们在PATH中放一个优先级高于真xclip的包装脚本，拦截这种"读 image/png"的调用，改用powershell.exe从 Windows 主机剪贴板取图、保存到临时目录、再通过wslpath回传给调用方。其它非图片场景（如读文本）则透传给真xclip，不影响日常使用。

步骤 1：确认前置条件

which powershell.exe   # 应该有路径，例如 /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe
which wslpath          # 应该是 /usr/bin/wslpath
which xclip            # 没有的话先装：sudo apt install -y xclip

如果powershell.exe找不到，说明 WSL 互操作被禁用了，在/etc/wsl.conf里加上：

[interop]
enabled=true
appendWindowsPath=true

之后在 PowerShell 里执行wsl --shutdown重启 WSL。

步骤 2：创建 xclip 包装脚本

把下面内容保存为/usr/local/bin/xclip：

#!/usr/bin/env bash
# WSL 下让 xclip 能读取 Windows 主机剪贴板里的图片，
# 用于让 vscode Paste Image 插件在 WSL Remote 模式下正常工作。

REAL_XCLIP="/usr/bin/xclip"

is_wsl() {
    grep -qiE "microsoft|wsl" /proc/version 2>/dev/null
}

wants_image_png() {
    local prev=""
    for arg in "$@"; do
        if [[ "$prev" == "-t" && "$arg" == "image/png" ]]; then
            return 0
        fi
        prev="$arg"
    done
    return 1
}

has_o_flag() {
    for arg in "$@"; do
        [[ "$arg" == "-o" ]] && return 0
    done
    return 1
}

if is_wsl && wants_image_png "$@" && has_o_flag "$@"; then
    PS_CMD='
        Add-Type -AssemblyName System.Windows.Forms
        Add-Type -AssemblyName System.Drawing
        $img = [System.Windows.Forms.Clipboard]::GetImage()
        if ($img -eq $null) { exit 2 }
        $tmp = [System.IO.Path]::GetTempPath() + "vscode_paste_" + [System.Guid]::NewGuid().ToString() + ".png"
        $img.Save($tmp, [System.Drawing.Imaging.ImageFormat]::Png)
        Write-Output $tmp
    '
    WIN_PATH="$(powershell.exe -NoProfile -NonInteractive -Command "$PS_CMD" 2>/dev/null | tr -d '\r\n')"

    if [ -n "$WIN_PATH" ]; then
        WSL_PATH="$(wslpath -u "$WIN_PATH" 2>/dev/null)"
        if [ -f "$WSL_PATH" ]; then
            cat "$WSL_PATH"
            rm -f "$WSL_PATH"
            exit 0
        fi
    fi
fi

exec "$REAL_XCLIP" "$@"

赋可执行权限：

sudo chmod +x /usr/local/bin/xclip

步骤 3：验证

在 Windows 上随便截一张图（Win+Shift+S、Snipaste、QQ截图都可以），回到 WSL 终端：

xclip -selection clipboard -t image/png -o > /tmp/test.png
file /tmp/test.png    # 期望输出：PNG image data, ...

输出PNG image data就说明桥接成功，回到 VSCode 直接Ctrl+Alt+V粘贴即可。

步骤 4（可选但建议）：关闭 VSCode 内置粘贴避免冲突

如果之前为了试方案 A 启用过 VSCode 内置 Markdown 粘贴，把这几项关掉，统一交给Paste Image处理：

"editor.experimental.pasteActions.enabled": false,
"markdown.copyFiles.destination": {},
"markdown.editor.filePaste.copyIntoWorkspace": "never"

1. 本文目标​

2. 准备工作​

3. 安装插件​

4. 插件的用法​

4.1. Markdown All in One​

4.1.1. 快捷键​

4.1.2. 创建/更新目录​

4.1.3. 给标题增加序号​

4.2. markdownlint​

4.2.1. 格式检查​

4.2.2. 文档格式化​

4.3. Markdown Table​

4.3.1. 格式化表格​

4.3.2. 插入表格列​

4.4. Markdown PDF​

4.5. Write Timestamp​

4.6. Paste Image​

4.6.1. WSL环境下无法粘贴Windows剪贴板的图片​