ARTICLE · 1137162
我给 LaTeX 做了一个插图小插件:直接粘贴、同步改名,还能先留个框
港島夜話我给 LaTeX 做了一个插图小插件：直接粘贴、同步改名，还能先留个框
写论文、整理讲义或者做报告时，你有没有遇到过这样的情况：正文写得很顺，轮到插图，却要停下来保存图片、想文件名、找文件夹，再把名称填进 LaTeX 代码。
图片一多，这些小操作就会反复打断思路。尤其是后来想改个更清楚的名称，还得同时修改代码和磁盘文件，一不留神就会遇到“找不到图片”。
于是，我给 VS Code 做了一个小插件：TeX Paste Image。
它把几个常用操作放到了写作现场：复制图片后直接粘贴，在光标旁选对齐方式；修改代码里的文件名，离开花括号后同步改名；图片还没准备好时，先插入一个能编译的方框。 多张图片一起复制，也可以选择横排或竖排。
先看一个实际效果：左边是 LaTeX 代码，右边是编译后的 PDF。
图 1：本文使用实际操作截图演示，图表中的数值均为虚构示例数据。
这篇文章从下载、安装讲起，再用几个例子带你走一遍。第一次接触这个插件，也可以照着操作。
一、先说清楚：适合什么使用情景？
本文假定你的电脑已经安装了本地 TeX 环境和桌面版 VS Code，并且能够正常编译 LaTeX 文档。 例如，你正在本地写论文、讲义、实验报告，想让插图更方便。
在此基础上，建议安装发布者为 James Yu 的 LaTeX Workshop：
安装 LaTeX Workshop 时，按 Ctrl+Shift+X 打开扩展面板，搜索它的名称，核对发布者再安装。也可以使用 LaTeX Workshop 官方扩展页面。
LaTeX Workshop 调用你已有的 TeX 工具；如果提示找不到 xelatex 或 latexmk，需要检查本地 TeX 路径和编译配置。官方安装说明
本文以 TeX Paste Image 0.4.1、Windows 桌面版为例。插件要求 VS Code 1.97 或以上。 macOS 已配置对应快捷键，但尚未完成同等实机验证；远程、WSL、容器和网页版也不属于这次演示范围。
二、从 GitHub 下载并安装
1. 下载正确的文件
项目已经放到 GitHub：
打开 TeX Paste Image 项目
只想使用插件，最直接的方式是点击：
下载最新版 tex-paste.vsix 安装包
也可以打开 Releases 版本发布页，找到最新版本，在 Assets 中下载 tex-paste.vsix。
图 2：安装插件请选择 tex-paste.vsix。下面的 Source code 是供查看、修改源码使用的压缩包。
VSIX 就是 VS Code 扩展安装包，下载后直接安装，不需要解压。 使用这个现成安装包，也不需要另外安装 Git、Node.js 或学习编程。
2. 在 VS Code 中“从 VSIX 安装”
tex-paste.vsix，完成安装。如果出现信任提示，请先核对文件来源。
图 3：找到这一项后，选择下载好的安装包。
也可以通过“扩展面板 → 右上角 … → 从 VSIX 安装”完成相同操作。VS Code 官方 VSIX 安装说明
安装后，在扩展面板搜索 @id:local.tex-paste，能看到 TeX Paste Image。发布者显示为 local，与当前安装包的标识一致。
图 4：本文演示的版本为 0.4.1。页面上的“禁用”和“卸载”按钮说明扩展已安装。
三、第一次插图：复制、粘贴、选位置
1. 准备一个练习文档
先建一个本地文件夹，在 VS Code 中打开它，再创建并保存 main.tex。可以从下面这段最小示例开始：
% !TeX program = xelatex\documentclass[UTF8]{ctexart}\usepackage{graphicx}\begin{document}\section{我的第一张图片}% 把光标放到下面的空白行，再粘贴图片\end{document}这个中文示例请使用 XeLaTeX 编译。已有自己的文档时，只要确认导言区加载了 \usepackage{graphicx} 即可。
先按 Ctrl+S 保存文件。 插件会把图片放到当前 .tex 文件所在的文件夹，因此需要先确定文档的位置。右下角的语言模式也应显示 LaTeX。
2. 复制一张图片
最容易上手的方式是：在 Windows 资源管理器里选中一张 PNG 或 JPG 图片，按 Ctrl+C。
截图工具提供的图片，或者浏览器中的“复制图片”，也可以使用。复制网页链接、图片网址，则是另一回事；初次练习建议先复制本地 PNG/JPG 文件。
3. 回到正文，按 Ctrl+V
把光标放到准备插图的空行，按 Ctrl+V。这时，选项会出现在光标附近：
居中 / 靠左 / 靠右。
图 5：可以直接点击，也可以用方向键选中，再按 Enter 或 Tab。
选定后，图片副本会保存到文档所在文件夹，正文自动插入类似这样的代码：
\begin{figure}[htbp] \centering \includegraphics[width=0.8\linewidth]{study-time.png} \caption{study-time} \label{fig:study-time}\end{figure}刚插入时，文件名是一个可编辑位置；按 Tab 可以继续跳到图片说明和标签。你可以把说明改成“一周学习时间”，把标签改成便于记忆的名称。
这里最常用的几处是：
\centering | |
width=0.8\linewidth | |
{study-time.png} | |
\caption{...} | |
\label{...} |
最后保存文档，使用 LaTeX Workshop 编译并打开 PDF。可以按 F1 搜索 LaTeX Workshop，选择 Build with recipe，使用自己已配置好的 XeLaTeX 方案；编译后通过 View LaTeX PDF file 查看结果。
如果菜单里还有 LaTeX Workshop 的其他代码提示，选择前面的三个图片对齐选项即可。需要取消时按 Esc。
四、在代码里改名，磁盘图片也跟着改
这是我很想解决的一处小麻烦：代码里已经写了图片名，为什么还要再去文件夹改一次？
比如，把下面的 study-time.png 改成更符合用途的 study-plan.png：
\includegraphics[width=0.8\linewidth]{study-plan.png}当光标还在文件名的花括号里时，磁盘文件暂时保持原名。 这样，名称输入到一半时不会反复改动文件。
图 6：上方已经输入 study-plan.png，下方文件列表仍是 study-time.png。图中截取了同一时刻的编辑区和文件列表。
等你按 Tab 跳到图片说明，或者点击别的行，光标离开这对花括号后，图片才改成新名称。
图 7：离开文件名后，文件列表已经变成 study-plan.png。
如果同一张图片在当前这份文档里出现了多次，默认会一起更新这些图片引用。不过，图片说明 caption、标签 label，以及其他 .tex 文件中的引用，需要你按实际需要处理。
有三件事要记住：
.png 写成 .jpg 不会完成格式转换。文件名联动适用于当前 .tex 目录及其子目录中、能够明确找到的图片。通过宏拼接的路径、外部目录、\graphicspath 隐式找到的图片，需要自行维护。
五、图片还没做好？先放一个 Box
写作时，图片经常比正文来得晚：实验还没完成，图表还在调整，或者想先把章节结构写好。
这时可以把光标放到正文中的空行，同时按下 Ctrl+Alt+P。
插件会直接插入一个默认居中的图片占位符。它使用一个尚不存在的文件名，例如 image-placeholder.png，编译后显示带边框的 Box。
图 8：图片还没放入文件夹时，PDF 中显示 Image placeholder 方框。
之后只需做两步：
.tex 所在文件夹，完整名称与代码一致，例如 image-placeholder.png。有了同名图片，原来的 Box 就会显示为图片。这背后使用的是 \IfFileExists：文件存在就插图，文件不存在就显示方框。
这个快捷键不读取剪贴板，也不会替你生成一张空白图片文件。 所以，无论剪贴板里有没有图片，都可以先留位置。
需要改占位名称时，可以直接编辑文件名。代码中的两处名称在插入时会联动；请保留 % TeX Paste placeholder 标记，方便插件识别它们的关联。多次插入会使用递增名称，避免混用。
如果最后准备的是 JPG，可在图片尚未放入时，把占位名称改成例如 experiment.jpg，离开文件名后再放入这个同名 JPG。
六、一次复制多张图片，选择横排或竖排
对比图、实验前后照片、两组统计结果，经常需要放在一起。
可以在资源管理器里按住 Ctrl 选中多张 PNG/JPG 文件，再按 Ctrl+C。
图 9：这里复制的是两个独立图片文件。
回到 .tex 正文按 Ctrl+V，流程是：
先选居中、靠左或靠右，再选横向排列或纵向排列。
图 10：识别到两张图片后，出现第二次选择。
横向排列适合把图片并排放置，方便读者比较。下面是实际编译结果：
图 11：两张图共用一个图片说明。示例数据不代表真实学习情况。
横排使用标准的 minipage 分配宽度；纵排则把图片逐张向下排列。默认把它们放进同一个 figure，共用一份 caption 和 label，每张图片的文件名仍可单独编辑。
如果你需要每张图分别编号、分别写说明，可以在生成的 LaTeX 代码上继续调整。
这里也有两个小提醒：图片顺序以系统提供的顺序为准，需要固定顺序时检查代码；并排图片太多会变小，建议按内容分成几组。
复制一张已经拼好的长图，得到的仍是一张图片。多图排列需要剪贴板实际提供多个图片文件。
七、记住这几个操作就够了
.tex 正文按 Ctrl+V | |
最后那个命令适合“图片已经放进文件夹，只差插入代码”的情况。它会查找当前文件夹内尚未被当前文档引用的图片。
想调整默认图片大小，可以按 Ctrl+, 打开设置，搜索 texPaste，修改 texPaste.width。大多数初次使用者保留默认设置就可以。
如果快捷键被其他扩展占用，先通过命令面板执行对应的 TeX Paste 命令，再到“键盘快捷方式”里调整绑定。
八、这些细节，知道了就能少走弯路
文件与路径
先保存 .tex，再插图。 从其他文件夹复制图片时，插件把副本保存到当前文档旁，原图片保留；后面的自动改名针对这份副本。
新手建议先在主文件 main.tex 中练习。若你编辑的是子目录中的章节文件，图片会保存到该章节文件旁，而编译时的图片搜索路径通常按主文档目录解析，需要相应调整。
图片优先使用 PNG/JPG。SVG、WebP、GIF 等格式可能需要先转换；这个插件不负责图片格式转换。文件名建议使用中文、字母、数字、下划线或连字符，避免 %、#、&、花括号等特殊字符。
排版与编译
居中、靠左、靠右，控制的是图片在图片环境中的对齐。 默认的 figure[htbp] 仍遵循 LaTeX 浮动规则，所以图片可能出现在后面，而不一定紧贴源码所在段落。
每个 label 应保持唯一。反复使用同一张图片时，最好检查标签，避免重复编号引用。PDF 没更新，也要确认重新编译的是当前主文档。
改名与撤销
自动改名默认更新当前文档中的同图引用，跨文档的引用请自行检查。重要文档保持正常备份，改名后及时保存代码。
撤销插入代码不会自动删除已经保存的图片。 确认不用后，可以自己清理未引用的文件。
更新插件
通过 VSIX 安装的扩展默认不自动更新。需要更新时，到 GitHub Releases 下载新的 tex-paste.vsix，再次“从 VSIX 安装”，再重新加载窗口。VS Code 官方说明
九、遇到问题，先检查这几项
.tex，语言模式是 LaTeX，扩展已启用；再试一次本地 PNG/JPG | |
.tex 正文，再尝试；也可从 F1 的 TeX Paste 命令中插入占位符，排查快捷键冲突 | |
.png.png，然后重新编译 | |
includegraphics | \usepackage{graphicx} |
仍然无法解决时，可以打开“查看 → 输出”，选择 TeX Paste Image 查看提示，再到项目的 Issues 页面反馈。附上系统、VS Code 和插件版本，以及最短的复现步骤，会更方便排查；截图和日志提交前记得去掉私人内容。
十、下载入口与完整教程
这个插件面向一个很具体的写作需求：让你在编辑 LaTeX 正文时，更顺手地处理图片。
先拿一份练习文档，复制一张 PNG，按 Ctrl+V 试一次；再试试改名和 Ctrl+Alt+P。几个常用动作熟悉之后，就可以把它用到自己的论文、讲义或报告里。
项目以 MIT 协议开源。欢迎试用，也欢迎反馈你在实际写作中遇到的问题。
演示版本：TeX Paste Image 0.4.1。配图来自 Windows 桌面环境的实际操作；文中的图表仅用于展示插件功能。