# MyFirstLaTeXProject

**Repository Path**: cmx1998/my-first-latex-project

## Basic Information

- **Project Name**: MyFirstLaTeXProject
- **Description**: 在 VS Code 中集成 LaTeX 环境并创建第一个文档；
LaTeX 是一款专业的文档排版系统，特别适合学术论文、技术文档和书籍的编写；
本项目将展示基础和复杂两种示例LaTeX的项目结构实践。

- **Primary Language**: TeX/LaTeX
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-15
- **Last Updated**: 2025-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyFirstLaTeXProject

## 介绍
在 VS Code 中集成 LaTeX 环境并创建第一个文档；
LaTeX 是一款专业的文档排版系统，特别适合学术论文、技术文档和书籍的编写；
本项目将展示基础和复杂两种示例LaTeX的项目结构实践。

## 基础环境要求

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

## 软件架构
VSCode插件 + LaTeX + Strawberry Perl

## 安装教程


### 1. 安装 TeX 发行版

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

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

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

1. 访问 [MiKTeX 官网](https://miktex.org/)
2. 下载 Windows 版本的安装程序
3. 运行安装程序，选择"基本安装"或"完全安装"

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

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

1. 访问 [TeX Live 官网](https://www.tug.org/texlive/)
2. 下载 Windows 版本的安装程序
3. 运行安装程序，建议选择"简单安装"模式
4. 安装过程可能需要较长时间（约1-2小时），请耐心等待

验证安装是否成功：

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

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

### 2. 安装 Strawberry Perl

1. 访问 [Strawberry Perl 官方下载地址](https://strawberryperl.com/releases.html)
2. 下载 Windows 版本的安装程序
3. 运行安装程序

验证安装是否成功：

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

### 3. 安装 VS Code LaTeX 扩展

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

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

### 4. 配置 VS Code LaTeX 环境

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

#### 基础配置

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

```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
}
```

#### 高级配置（可选）

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

```json
{
  "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 文档了。

#### 创建项目结构

建议的项目结构：

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

#### 编写基础文档

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

```latex
\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`文件：
```latex
% 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`文件：
```latex
% 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`文件：
```latex
% 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`文件：
```latex
% 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` 文件：

```bibtex
@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. 编译和预览文档

#### 自动编译和预览

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

#### 手动编译

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

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

## 使用说明

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

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

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

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

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

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

## LaTeX Workshop 常用功能

### 代码片段和自动补全

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

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

### 文档结构导航

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

### 同步滚动

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

## 项目结构建议

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

```text
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` 验证环境配置：

```latex
\documentclass{article}
\begin{document}
Hello LaTeX World!

如果能看到这个文档，说明你的 LaTeX 环境配置成功！

当前时间: \today
\end{document}
```

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

## 故障排除

1. **编译错误 "latexmk not found"**：
   - 确认 TeX 发行版已正确安装并添加到 PATH
   - 重启 VS Code 尝试
   - 在终端中运行 `latexmk --version` 验证安装

2. **PDF 预览无法显示**：
   - 检查编译是否成功（查看 VS Code 的 PROBLEMS 面板）
   - 确认 PDF 查看器配置正确
   - 尝试使用外部查看器：`"latex-workshop.view.pdf.viewer": "external"`

3. **参考文献无法编译**：
   - 确保已安装 BibTeX
   - 运行完整的编译流程：LaTeX → BibTeX → LaTeX → LaTeX
   - 在命令面板中选择 "LaTeX Workshop: Build with recipe"

4. **图片无法显示**：
   - 检查图片路径是否正确
   - 确认图片格式支持（PDF、PNG、JPG）
   - 确保已安装 `graphicx` 包

5. **中文支持问题**：
   - 使用 XeLaTeX 或 LuaLaTeX 引擎
   - 添加 `\usepackage{ctex}` 包
   - 修改编译工具为 xelatex 或 lualatex

6. **编译时间过长**：
   - MiKTeX 首次编译会自动下载缺少的包，这是正常现象
   - 后续编译会快很多，因为包已经缓存
   - 如果希望避免这种情况，可以：
      - 安装时选择"完全安装"模式
      - 使用 TeX Live 完整版
      - 预先安装常用包：mpm --install=scheme-full（MiKTeX 包管理器）

## 进阶技巧

### 自定义编译流程

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

```json
{
  "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` 文件，排除编译生成的文件：

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

## 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request

## 参考资料

1. [LaTeX Project 官方网站](https://www.latex-project.org/)
2. [TeX Live 安装指南](https://www.tug.org/texlive/)
3. [LaTeX Workshop 扩展文档](https://github.com/James-Yu/LaTeX-Workshop/wiki)
4. [LaTeX 入门指南](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes)
5. [BibTeX 参考文献管理](http://www.bibtex.org/)