在 VS Code 中集成 LaTeX 环境并创建第一个文档

概述

LaTeX 是一款专业的文档排版系统，特别适合学术论文、技术文档和书籍的编写。本文将详细介绍如何在 VS Code 中配置完整的 LaTeX 环境，从安装必要的组件到编写和编译第一个 LaTeX 文档，打造高效的文档编写工作流。

基础环境要求

Windows 10 或 Windows 11 操作系统
已安装 VS Code（建议最新版本）
安装Strawberry Perl
安装TeX发行版

软件架构

VSCode插件 + LaTeX + Strawberry Perl

码云仓库

地址：https://gitee.com/cmx1998/my-first-latex-project.git

安装教程

1. 安装 TeX 发行版

TeX 发行版是 LaTeX 的核心组件，提供了编译文档所需的全部工具。

方法一：安装 MiKTeX（轻量级，强烈推荐）

MiKTeX 是一个轻量级的 TeX 发行版，适合初学者。

访问 MiKTeX 官网
下载 Windows 版本的安装程序
运行安装程序，选择"基本安装"或"完全安装"

关于编译时间长的问题说明：

首次编译时，MiKTeX 会自动下载缺少的包，这可能导致编译时间较长
这是正常现象，MiKTeX 采用"按需安装"策略
后续编译会快很多，因为所需的包已经缓存
如果希望避免这种情况，可以在安装 MiKTeX 时选择"完全安装"

方法一：安装 TeX Live（进阶之选）

TeX Live 是一个完整的 TeX 系统，支持跨平台使用。

访问 TeX Live 官网
下载 Windows 版本的安装程序
运行安装程序，建议选择"简单安装"模式
安装过程可能需要较长时间（约1-2小时），请耐心等待

验证安装是否成功：

# 打开终端，执行以下命令
latex --version

若输出版本信息，则表示安装成功。

2. 安装 Strawberry Perl

访问 Strawberry Perl 官方下载地址
下载 Windows 版本的安装程序
运行安装程序

验证安装是否成功：

# 打开终端，执行以下命令
perl --version

3. 安装 VS Code LaTeX 扩展

VS Code 通过扩展提供对 LaTeX 的支持，安装以下扩展：

打开 VS Code
进入扩展市场（Ctrl+Shift+X）
搜索并安装以下扩展：
- LaTeX Workshop（核心扩展，提供编译、预览等功能，必须安装）
- LanguageTool（可选，但不推荐，语法检查）
- Spell Right（可选，但不推荐，拼写检查）

4. 配置 VS Code LaTeX 环境

安装扩展后，需要进行适当的配置以优化使用体验。

基础配置

在 VS Code 中打开设置（Ctrl+,或者左下角点击齿轮状按钮并点击Settings），搜索 "latex" 进行配置(Extensions目录下的LaTeX是LaTeX Workshop插件的配置)，或直接编辑 settings.json 文件：

{"latex-workshop.latex.autoBuild.run": "onSave","latex-workshop.latex.recipe.default": "latexmk","latex-workshop.latex.tools": [{"name": "latexmk","command": "latexmk","args": ["-synctex=1","-interaction=nonstopmode","-file-line-error","-pdf","-outdir=%OUTDIR%","%DOC%"]}],"latex-workshop.latex.recipes": [{"name": "latexmk","tools": ["latexmk"]}],"latex-workshop.view.pdf.viewer": "tab","latex-workshop.latex.autoClean.run": "onFailed","latex-workshop.message.error.show": false,"latex-workshop.message.warning.show": false
}

高级配置（可选）

如需更多自定义功能，可添加以下配置：

{"latex-workshop.latex.outDir": "%DIR%/build","latex-workshop.synctex.afterBuild.enabled": true,"latex-workshop.latex.autoBuild.interval": 5000,"latex-workshop.intellisense.package.enabled": true
}

5. 创建第一个 LaTeX 文档

现在可以创建并编译第一个 LaTeX 文档了。

创建项目结构

建议的项目结构：

latex-project/
├── main.tex          # 主文档
├── chapters/         # 章节目录
│   ├── introduction.tex
│   └── conclusion.tex
├── images/           # 图片资源
├── references.bib    # 参考文献
└── build/            # 编译输出（自动生成）

编写基础文档

创建 main.tex 文件，输入以下内容：

\documentclass[12pt,a4paper,UTF8]{ctexart} % ctexart提供中文支持，显式指定UTF8避免报错% 预加载包和配置
\usepackage[utf8]{inputenc}
\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{hyperref}
\usepackage{xcolor}% 文档信息
\title{我的第一个 LaTeX 文档}
\author{你的名字}
\date{\today}\begin{document}% 标题页
\maketitle% 摘要
\begin{abstract}
这是一篇使用 VS Code 和 LaTeX Workshop 编写的示例文档。本文演示了 LaTeX 的基本功能，包括章节、数学公式、图片和参考文献。
\end{abstract}\tableofcontents
\newpage% 正文开始
\input{chapters/introduction}
\input{chapters/math}
\input{chapters/images}
\input{chapters/conclusion}% 参考文献
\clearpage                  % 确保在新页面开始参考文献
\bibliographystyle{plain}
\bibliography{references}
\vspace{1em}                % 添加一点垂直间距\end{document}

创建章节文件

创建chapters/introduction.tex文件：

% introduction.tex
\section{引言}
\label{sec:introduction}这是引言部分。LaTeX 是一个强大的文档排版系统，特别适合编写学术论文和技术文档\cite{lamport1994latex}。使用 VS Code 配合 LaTeX Workshop 扩展，可以让我们在编写 LaTeX 文档时获得代码高亮、自动补全和实时预览等功能，大大提高了编写效率\cite{mittelbach2004latex}。\subsection{LaTeX 的优势}
LaTeX 相比于传统的文字处理软件具有以下优势\cite{knuth1984literate}：\begin{itemize}\item \textbf{专业的排版效果}：自动处理版面布局、字体、间距等\item \textbf{强大的数学公式支持}：能够完美排版复杂的数学表达式\item \textbf{参考文献管理}：通过 BibTeX 自动管理引用文献\item \textbf{版本控制友好}：纯文本格式便于使用 Git 等工具管理\item \textbf{跨平台兼容}：在不同操作系统上获得一致的输出效果
\end{itemize}\subsection{开发环境配置}
本文介绍了如何在 Windows 系统上配置完整的 LaTeX 开发环境，包括：\begin{enumerate}\item 安装 TeX 发行版（TeX Live 或 MiKTeX）\item 配置 VS Code 和 LaTeX Workshop 扩展\item 创建和管理 LaTeX 项目结构\item 编译和预览文档
\end{enumerate}通过这些步骤，你可以建立一个高效的文档编写工作流。

创建chapters/math.tex文件：

% math.tex
\section{数学公式}
\label{sec:math}LaTeX 最强大的功能之一是数学公式排版。以下是一些示例：\subsection{行内公式}
爱因斯坦的质能方程：$E = mc^2$。勾股定理：$a^2 + b^2 = c^2$。\subsection{独立公式}
二次方程求根公式：
\[
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
\]\subsection{多行公式}
\begin{align}
f(x) &= \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d\xi \\
\hat{f}(\xi) &= \int_{-\infty}^{\infty} f(x) e^{-2 \pi i \xi x} dx
\end{align}\subsection{矩阵和行列式}
矩阵表示：
\[
A = \begin{bmatrix}
a_{11} & a_{12} & \cdots & a_{1n} \\
a_{21} & a_{22} & \cdots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{m1} & a_{m2} & \cdots & a_{mn}
\end{bmatrix}
\]行列式：
\[
\det(A) = \begin{vmatrix}
a & b \\
c & d
\end{vmatrix} = ad - bc
\]

创建chapters/images.tex文件：

% images.tex
\section{图片插入}
\label{sec:images}在 LaTeX 中插入图片需要使用 \texttt{graphicx} 包和 \texttt{figure} 环境。\begin{figure}[ht]
\centering
% 请将 example-image.png 替换为实际图片文件
\includegraphics[width=0.5\textwidth]{images/example-image.png}
\caption{示例图片}
\label{fig:example}
\end{figure}图 \ref{fig:example} 展示了一个图片插入的示例。图片的位置可以通过可选参数控制：\begin{itemize}\item \texttt{h}：当前位置（here）\item \texttt{t}：页面顶部（top）\item \texttt{b}：页面底部（bottom）\item \texttt{p}：单独一页（page）
\end{itemize}\subsection{图片格式建议}
为了获得最佳效果，建议使用以下图片格式：\begin{table}[ht]
\centering
\caption{支持的图片格式}
\label{tab:image-formats}
\begin{tabular}{|l|l|l|}
\hline
\textbf{格式} & \textbf{优点} & \textbf{缺点} \\
\hline
PDF & 矢量图，缩放无损 & 不适合照片 \\
PNG & 无损压缩，适合图表 & 文件较大 \\
JPG & 有损压缩，适合照片 & 质量损失 \\
\hline
\end{tabular}
\end{table}

创建chapters/conclusion.tex文件：

% conclusion.tex
\section{结论}
\label{sec:conclusion}通过本文的示例，我们学习了如何在 VS Code 中配置和使用 LaTeX 环境。以下是一些关键要点总结：\subsection{环境配置要点}
\begin{itemize}\item 选择合适的 TeX 发行版：TeX Live（完整）或 MiKTeX（轻量）\item 正确配置 VS Code 的 LaTeX Workshop 扩展\item 理解项目结构的重要性，合理组织文档文件
\end{itemize}\subsection{LaTeX 使用技巧}
在编写 LaTeX 文档时，以下技巧可以提高效率：\begin{itemize}\item 使用章节文件（如 \verb|introduction.tex|）来组织大型文档\item 善用标签（\verb|\label|）和引用（\verb|\ref|）功能\item 利用 BibTeX 管理参考文献\item 定期编译检查错误，避免错误积累
\end{itemize}\subsection{进一步学习}
要深入学习 LaTeX，建议：\begin{enumerate}\item 阅读 LaTeX 官方文档和教程\item 练习编写不同类型的文档（报告、论文、书籍）\item 学习使用更高级的包和自定义命令\item 参与 LaTeX 社区，学习最佳实践
\end{enumerate}\subsection{最终建议}
\begin{quote}
\textit{``LaTeX 的学习曲线可能较陡，但一旦掌握，你将获得无与伦比的文档排版控制能力。坚持练习，你会逐渐体会到它的强大之处。''}
\end{quote}希望这个示例文档能够帮助你开始使用 LaTeX，并在学术或专业写作中发挥作用\cite{chen2005chinese}。。

创建参考文献文件

创建 references.bib 文件：

@book{lamport1994latex,title={LaTeX: A Document Preparation System},author={Lamport, Leslie},year={1994},publisher={Addison-Wesley Professional},note={LaTeX 的经典教程}
}@article{knuth1984literate,title={Literate programming},author={Knuth, Donald E.},journal={The Computer Journal},volume={27},number={2},pages={97--111},year={1984},publisher={Oxford University Press},note={文学编程的开创性论文}
}@book{mittelbach2004latex,title={The {LaTeX} Companion},author={Mittelbach, F. and Goossens, M.},year={2004},publisher={Addison-Wesley},edition={2nd},note={LaTeX 的权威参考书}
}@article{chen2005chinese,title={中文 LaTeX 排版技巧},author={陈, 晓和 and 张, 明华},journal={计算机应用},volume={25},number={3},pages={45--48},year={2005},note={中文排版相关论文}
}

6. 编译和预览文档

自动编译和预览

保存 main.tex 文件（根据配置，保存时会自动编译）
在 VS Code 中，按下 Ctrl+Shift+P 打开命令面板
输入 "LaTeX Workshop" 查看可用命令
选择 "View LaTeX PDF" 在侧边栏打开 PDF 预览

手动编译

如果自动编译未启用，可以手动编译：

在 VS Code 中打开 main.tex 文件
按下 Ctrl+Alt+B 编译文档
按下 Ctrl+Alt+V 预览生成的 PDF

开发工作流建议

方案 A：实时编译（推荐日常写作）

适合快速写作和即时预览：

启用自动编译（"latex-workshop.latex.autoBuild.run": "onSave"）
编写 LaTeX 代码
保存文件后自动编译并更新预览
使用 VS Code 的分屏功能，左侧编辑代码，右侧预览 PDF

方案 B：手动编译（推荐大型文档）

对于包含大量图片和复杂引用的文档，手动编译更稳定：

禁用自动编译
编写完一个完整章节后手动编译
使用 Ctrl+Alt+B 编译，Ctrl+Alt+V 预览

LaTeX Workshop 常用功能

代码片段和自动补全

LaTeX Workshop 提供了丰富的代码片段：

输入 \begin 然后按 Tab：快速创建环境
输入 \section 然后按 Tab：创建章节
输入 \figure 然后按 Tab：创建图片环境

文档结构导航

按下 Ctrl+Shift+P
输入 "LaTeX Workshop: Navigate to section"
选择要跳转的章节

同步滚动

在 PDF 预览中点击位置，VS Code 编辑器会自动跳转到对应的源代码位置。

项目结构建议

对于复杂的 LaTeX 项目，推荐以下结构：

thesis/
├── main.tex                  # 主文档
├── preamble.tex              # 导言区设置
├── chapters/                 # 章节文件
│   ├── 01-introduction.tex
│   ├── 02-literature.tex
│   ├── 03-methodology.tex
│   ├── 04-results.tex
│   └── 05-conclusion.tex
├── frontmatter/              # 前言部分
│   ├── abstract.tex
│   ├── acknowledgements.tex
│   └── dedication.tex
├── appendices/               # 附录
│   └── appendix-a.tex
├── images/                   # 图片资源
│   ├── diagrams/
│   └── photos/
├── styles/                   # 自定义样式
│   └── custom.sty
├── references.bib            # 参考文献数据库
└── build/                    # 编译输出（在 .gitignore 中排除）

验证环境

创建测试文档 test-latex.tex 验证环境配置：

\documentclass{article}
\begin{document}
Hello LaTeX World!如果能看到这个文档，说明你的 LaTeX 环境配置成功！当前时间: \today
\end{document}

编译该文档，如果成功生成 PDF 并显示内容，则环境配置正确。

故障排除

编译错误 "latexmk not found"：
- 确认 TeX 发行版已正确安装并添加到 PATH
- 重启 VS Code 尝试
- 在终端中运行 latexmk --version 验证安装
PDF 预览无法显示：
- 检查编译是否成功（查看 VS Code 的 PROBLEMS 面板）
- 确认 PDF 查看器配置正确
- 尝试使用外部查看器："latex-workshop.view.pdf.viewer": "external"
参考文献无法编译：
- 确保已安装 BibTeX
- 运行完整的编译流程：LaTeX → BibTeX → LaTeX → LaTeX
- 在命令面板中选择 "LaTeX Workshop: Build with recipe"
图片无法显示：
- 检查图片路径是否正确
- 确认图片格式支持（PDF、PNG、JPG）
- 确保已安装 graphicx 包
中文支持问题：
- 使用 XeLaTeX 或 LuaLaTeX 引擎
- 添加 \usepackage{ctex} 包
- 修改编译工具为 xelatex 或 lualatex
编译时间过长：
- MiKTeX 首次编译会自动下载缺少的包，这是正常现象
- 后续编译会快很多，因为包已经缓存
- 如果希望避免这种情况，可以：
  - 安装时选择"完全安装"模式
  - 使用 TeX Live 完整版
  - 预先安装常用包：mpm --install=scheme-full（MiKTeX 包管理器）

进阶技巧

自定义编译流程

对于需要特殊处理的文档，可以自定义编译配方：

{"latex-workshop.latex.recipes": [{"name": "xelatex","tools": ["xelatex", "bibtex", "xelatex", "xelatex"]}],"latex-workshop.latex.tools": [{"name": "xelatex","command": "xelatex","args": ["-synctex=1","-interaction=nonstopmode","-file-line-error","-output-directory=%OUTDIR%","%DOC%"]}]
}

使用 Git 进行版本控制

创建 .gitignore 文件，排除编译生成的文件：

# LaTeX 编译输出
build/
*.aux
*.log
*.out
*.toc
*.lof
*.lot
*.bbl
*.blg
*.synctex.gz

参考资料

LaTeX Project 官方网站
TeX Live 安装指南
LaTeX Workshop 扩展文档
LaTeX 入门指南
BibTeX 参考文献管理