使用 LaTex+VSCode+git 进行论文格式管理以及版本控制

前言

LaTeX 作为一种强大的排版系统，对于理工科，特别是公式比较多的专业，其重要性自不必多说。

而选择一个比较好的编译器是很重要的，至少对笔者而言是如此。TeX Live自带编辑器TeXworks editor，但是其编译速度比较慢，并且页面不是很美观。本文介绍如何将LaTex与VSCode结合使用。

可以看到，它不仅能够对代码高亮，不同级别括号用不同颜色标注了，颜值也很高。vscode 最突出的特点就是其强大的插件功能，每个使用者都能够根据自己的需求和想法下载相应的插件，从而将之配置为高度个性化的编辑器。可以这么说，每个使用者的 vscode 都不一样，为其专属定制编辑器。

TeX Live下载及安装

笔者选用的 Tex 系统是 TeX Live

TeX Live下载网址

点击下图中download from a nearby CTAN mirror

下载.iso文件

下载之后正常安装即可，时间可能会比较久，耐心等待。

安装完成后，电脑开始界面会出现这些东西

可以打开TeXworks editor浏览一下它的界面

代码高亮也就勉勉强强，并且不支持自动补全，而且编译速度太慢。初学者可以用它来练练手，如果真的要用LaTex写论文的话，建议使用其它更好的工具（例如VSCode）。

VSCode安装及配置

VSCode官网

在官网下载及安装便可，这是一个非常轻量级的代码编辑软件，跟随官网教程操作即可。

LaTeX Workshop安装

在VSCode中的扩展商店搜索LaTeX Workshop插件，单击安装即可（我这里由于已经安装了，所以只有一个小齿轮按钮）。

将工作区另存为，随便命名即可

然后设置该工作区的配置文件

配置文件中的json代码如下，初始时应该只有"folders"中有内容，"settings"内容为空。你只需要修改"settings"中的内容即可（在代码最后面，后有标注需要修改）

{
	"folders": [
		{
			// "path": "LaTex"
			"path":"Latex_gitee"
		}
	],
	"settings": {
		// start:为latex所添加
		"latex-workshop.latex.autoBuild.run": "never",
		"latex-workshop.showContextMenu": true,
		"latex-workshop.intellisense.package.enabled": true,
		"latex-workshop.message.error.show": false,
		"latex-workshop.message.warning.show": false,
		"latex-workshop.latex.tools": [
			{
				"name": "xelatex",
				"command": "xelatex",
				"args": [
					"-synctex=1",
					"-interaction=nonstopmode",
					"-file-line-error",
					"%DOCFILE%"
				]
			},
			{
				"name": "pdflatex",
				"command": "pdflatex",
				"args": [
					"-synctex=1",
					"-interaction=nonstopmode",
					"-file-line-error",
					"%DOCFILE%"
				]
			},
			{
				"name": "latexmk",
				"command": "latexmk",
				"args": [
					"-synctex=1",
					"-interaction=nonstopmode",
					"-file-line-error",
					"-pdf",
					"-outdir=%OUTDIR%",
					"%DOCFILE%"
				]
			},
			{
				"name": "bibtex",
				"command": "bibtex",
				"args": [
					"%DOCFILE%"
				]
			}
		],
		"latex-workshop.latex.recipes": [
			{
				"name": "XeLaTeX",
				"tools": [
					"xelatex"
				]
			},
			{
				"name": "PDFLaTeX",
				"tools": [
					"pdflatex"
				]
			},
			{
				"name": "BibTeX",
				"tools": [
					"bibtex"
				]
			},
			{
				"name": "LaTeXmk",
				"tools": [
					"latexmk"
				]
			},
			{
				"name": "xelatex -> bibtex -> xelatex*2",
				"tools": [
					"xelatex",
					"bibtex",
					"xelatex",
					"xelatex"
				]
			},
			{
				"name": "pdflatex -> bibtex -> pdflatex*2",
				"tools": [
					"pdflatex",
					"bibtex",
					"pdflatex",
					"pdflatex"
				]
			},
			{
				"name": "xe->bib->xe->xe",
				"tools": [
					"xelatex",
					"bibtex",
					"xelatex",
					"xelatex"
				]
			},
		],
		"latex-workshop.latex.clean.fileTypes": [
			"*.aux",
			"*.bbl",
			"*.blg",
			"*.idx",
			"*.ind",
			"*.lof",
			"*.lot",
			"*.out",
			"*.toc",
			"*.acn",
			"*.acr",
			"*.alg",
			"*.glg",
			"*.glo",
			"*.gls",
			"*.ist",
			"*.fls",
			"*.log",
			"*.fdb_latexmk"
		],
		"latex-workshop.latex.autoClean.run": "onFailed",
		"latex-workshop.latex.recipe.default": "lastUsed",
		"latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
		//PDF阅读器设置
		"latex-workshop.view.pdf.viewer": "tab",//tab:内置PDF阅读器；external:外置PDF阅读器；browser:使用电脑默认浏览器进行 pdf 查看；
		"latex-workshop.view.pdf.ref.viewer":"auto",
		"latex-workshop.view.pdf.external.viewer.command": "D:/setup/SumatraPDF/SumatraPDF.exe", // 注意修改路径
		"latex-workshop.view.pdf.external.viewer.args": [
			"%PDF%"
		],
		"latex-workshop.view.pdf.external.synctex.command": "D:/setup/SumatraPDF/SumatraPDF.exe", // 注意修改路径
		"latex-workshop.view.pdf.external.synctex.args": [
			"-forward-search",
			"%TEX%",
			"%LINE%",
			"%PDF%"
		],
		"git.autofetch": true
		// end:为latex所添加
	}
}

这几个地方需要修改 （如果你不配置SumatraPDF作为外部PDF阅读器的话（后文会提到），后两处修改可以直接无视）

"latex-workshop.view.pdf.viewer": "tab",//tab:内置PDF阅读器；external:外置PDF阅读器；browser:使用电脑默认浏览器进行 pdf 查看；
"latex-workshop.view.pdf.external.viewer.command": "D:/setup/SumatraPDF/SumatraPDF.exe", // 注意修改路径
"latex-workshop.view.pdf.external.synctex.command": "D:/setup/SumatraPDF/SumatraPDF.exe", // 注意修改路径

tex文件编译

• 测试文件下载
  测试所用的 tex 文件
  点击下图红框位置进行下载（如果你熟悉git命令行操作的话，可以直接在本地进行克隆）
  

点击，文件 — 将文件夹添加到工作区，然后选中下载的zip解压后的文件夹。

打开其中的.tex格式文件（我的文件名被修改过，可能与你下载的不同，你无需在意，找到.tex格式文件再单击打开即可）

由于进行测试的文件中涉及参考文献的引用（.bib的编译），故而选择xelatex -> bibtex -> xelatex*2编译链。（注意，你这里所看到的编译链都是在工作区的配置文件中设置过的，如果你需要设置新的编译链，自行增添即可）

点到tex文件中，Ctrl+Alt+V 查看pdf（此时是内置pdf查看器打开）

正向同步：单击任一行代码，右键，SyncTex from cursor。此时右侧pdf会自动跳转至改行代码对应位置

反正同步：在pdf中任一处双击，右侧代码区会自动跳转至改行文字对应的代码。

外部PDF查看器（SumatraPDF）

您可自行选择是否需要设置此部分内容。

有的时候，由于想要看到 pdf 文件的完整展现效果（例如目录），使用内置查看器已无法满足需求，这时可以使用外部查看器进行查看。

笔者选择 SumatraPDF 作为外部查看器，该软件的优点在于在具有 pdf 阅读功能的同时很轻量，安装包不到 10MB 大小，且支持双向同步功能。通过调整其与 vscode 的窗口位置，能够在拥有这些优势的同时，达到与内置 pdf 查看具有相同的效果。

SumatraPDF官网

正常安装即可，记住安装路径。

如果需要使用外部PDF查看功能，在工作区设置文件中更改下面的代码，PDF查看查看器设置为external，并将路径更改为自己的安装路径：

"latex-workshop.view.pdf.viewer": "external",//tab:内置PDF阅读器；external:外置PDF阅读器；browser:使用电脑默认浏览器进行 pdf 查看；
"latex-workshop.view.pdf.external.viewer.command": "D:/setup/SumatraPDF/SumatraPDF.exe", // 注意修改路径
"latex-workshop.view.pdf.external.synctex.command": "D:/setup/SumatraPDF/SumatraPDF.exe", // 注意修改路径

点到tex文件中，Ctrl+Alt+V 查看pdf（此时是外部pdf查看器打开），可以看到，同时显示出了pdf的目录

可能是最近VSCode更新的缘故或者SumatraPDF更新的缘故（总之是未知原因），SumatraPDF的反向同步功能不太好使了（正向同步功能没有问题）。如果要使用SumatraPDF的反向同步功能，还需要进行如下设置。点击高级选项

添加如下内容

//注意修改为自己的Microsoft VS Code安装路径
InverseSearchCmdLine = "D:\Code\VS code\Microsoft VS Code\Code.exe" "D:\Code\VS code\Microsoft VS Code\resources\app\out\cli.js"  --ms-enable-electron-run-as-node -r -g "%f:%l"
EnableTeXEnhancements = true

此时可以正常使用反向同步了（与内置PDF查看器的操作完全一致，这里就不赘述了）

注意，并不是任何一个PDF阅读器都适合作为VSCode中LaTex的外部PDF查看器，极大的可能是，你通常使用的PDF阅读器并不支持双向同步功能。而SumatraPDF支持双向同步功能，这才是选择它的最主要原因。

使用git进行版本控制

准备工作

• 你需要先安装git，一路next即可
• 在Gitee注册一个账号，并创建新项目（也可以使用GitHub，但是国内网访问速度极慢，push时时常timed out，建议选择Gitee）
  仓库选择“私有”，其余任意设置即可

在Windows打开git bash

设置自己的全局用户名和邮箱

$ git config --global user.name "Your Name"
$ git config --global user.email "email@example.com"

SSH连接

创建SSH Key，之前看下在C:\Users&yourname&目录有没有.ssh文件夹，如果有打开看看有没有id_rsa和id_rsa.pub这两个文件，如果已经有了，可直接使用。如果没有，打开Git Bash （这个和前面设置全局用户名邮箱那个步骤是一样的，打开输入即可，由于是全局设置没必要纠结在哪个文件夹打开），输入一下命令，创建SSH Key：

$ ssh-keygen -t rsa -C "youremail@example.com"

你需要把邮件地址换成你自己的邮件地址，然后一路回车，使用默认值即可，由于这个Key是自己使用的，为了方便无需设置密码。

如果顺利的话，在C:\Users&yourname&用户主目录里找到.ssh目录 （如果没有可能是文件夹被隐藏了，设置显示隐藏的文件夹即可） ，里面有id_rsa和id_rsa.pub两个文件，这两个就是SSH Key的秘钥对，id_rsa是私钥别泄露出去，id_rsa.pub是公钥可以告诉别人。

在C:\Users&yourname.ssh&文件夹里面找到id_rsa.pub这个文件，使用vscode打开（不要用记事本），复制其中的内容备用。

在Gitee中点击设置

点击SSH公钥，把从vscode里面打开的之前复制备用的id_rsa.pub文件内容复制进来，标题随便写，然后点击确定即可。

随后弹出的页面会让你验证Gitee密码，输入即可。

我们接着需要打开Git Bash，输入

ssh -T git@gitee.com

需要确认并添加主机到本机SSH可信列表。若返回
Hi XXX! You’ve successfully authenticated, but Gitee.com does not provide shell access. 内容，则证明添加成功。

这个连接测试是必须的，否则无法克隆！

从远程克隆

打开VSCode，快捷键Ctrl+shift+P，输入git clone，然后回车

在新出现的窗口我们需要输入一下Gitee项目的SSH地址，回到你的Gitee项目，复制SSH链接

粘贴SSH链接

回车后会让你选择一个文件夹进行保存，路径最好不要有中文

然后将该文件夹添加到LaTex工作区中，有一个非常简单的方法：在配置文件中直接更改为这个文件夹（该文件夹要与工作区在同一目录下）。

此时如果更改文件或者新建文件，左侧第三个图标会亮起，右下角的数字代表你修改或新建的文件个数。

点击文件后的 + 可以将其提交至缓存区，这里建议只需提交.tex文件和.bib文件以及Figures文件夹下的图片（其余文件均为编译生成的中间文件），然后点击最上面的对号
即可进行提交（同步至gitee仓库），每次提交前最好在对号下面一行的消息栏中输入一些提示信息（例如本次修改增添了文章的摘要部分），方便后续进行版本回退。

点击左下角的圆圈也可以进行同步，效果一致。

每次提交的日志信息展示在这里

点击...可以进行拉取、推送、克隆等多种操作，可以自己进行探索

VSCode中使用git进行版本回退有两种方法，

• 在git bash执行命令git reset --hard <commitid>
• 安装插件，Git Graph Git Graph - Visual Studio Marketplace，右键点击reset进行版本回退

---