使用Codex在本地配置MiKTeX自动编译

在 LaTeX 长文档项目中，如果每次都手动执行 xelatex、bibtex、再重复运行 xelatex，不仅麻烦，而且很容易遗漏步骤。本文记录如何使用 Codex 在 Windows 本地为 MiKTeX 配置自动编译流程，实现一键编译、临时文件集中管理、PDF 输出、分章字数统计和 Git 忽略规则配置。

一、配置目标

本次配置的目标是建立一个可复用的本地 LaTeX 自动编译方案：

使用本地 MiKTeX 编译项目
使用 xelatex 支持中文、ctex 和 fontspec
自动执行 xelatex -> bibtex -> xelatex -> xelatex
临时文件统一放入 build/
最终 PDF 输出到项目根目录
自动生成 Markdown 格式字数统计报告
配置 .gitignore，避免编译产物进入版本管理
配置 .codexignore，减少 Codex token 消耗

二、项目环境

示例项目环境如下：

MiKTeX:
E:/Program Files/MiKTeX/miktex/bin/x64

Strawberry Perl:
E:/Strawberry/perl/bin/perl.exe

LaTeX 主文件:
00-Main.tex

由于主文件中使用了 ctex 和 fontspec，因此编译引擎选择 xelatex。

三、给 Codex 的 Prompt

使用前请先将【本机配置项】中的内容修改成目标机器的实际配置路径：

请在当前 LaTeX 项目中配置一个 Windows 本地自动编译流程，用于 MiKTeX + XeLaTeX 编译中文书稿。

【本机配置项】

1. MiKTeX bin 路径
MIKTEX_BIN=E:/Program Files/MiKTeX/miktex/bin/x64

2. Strawberry Perl 可执行文件路径
PERL_EXE=E:/Strawberry/perl/bin/perl.exe

3. texcount.pl 路径
TEXCOUNT_PL=E:/Program Files/MiKTeX/scripts/texcount/texcount.pl

4. LaTeX 主文件名，不带 .tex
MAIN=00-Main

5. 构建目录
BUILD=build

6. 最终 PDF 文件名
ROOT_PDF=%MAIN%.pdf

7. 字数统计 PowerShell 脚本路径
WORDCOUNT_SCRIPT=build/tools/wordcount-report.ps1

8. 章节文件列表，使用英文分号分隔
CHAPTER_FILES=0-Preface.tex;1-Introduction.tex;2-LCM Application.tex;3-Theory.tex;4-Preform.tex;5-resin-processibility-characterization.tex;6-filling-simulation.tex;8-写在最后.tex

【需要实现的功能】

1. 新增 compile.bat
- 所有路径、主文件名、构建目录、PDF 输出名、章节列表都集中定义在脚本开头。
- 使用本地 MiKTeX，不依赖系统 PATH。
- 使用 xelatex 编译，因为项目包含中文、ctex 或 fontspec。
- 所有 LaTeX 临时文件统一输出到 build/。
- 最终 PDF 复制到项目根目录。

2. 编译流程
- 自动执行：
  xelatex -> bibtex -> xelatex -> xelatex
- xelatex 使用参数：
  -interaction=nonstopmode
  -file-line-error
  -output-directory=%BUILD%
- BibTeX 在 %BUILD% 目录内运行。
- 设置：
  BIBINPUTS=.;..;%BIBINPUTS%
  以便 BibTeX 能找到根目录下的 .bib 文件。
- 每一步失败时停止，并提示查看 %BUILD%/%MAIN%.log。

3. PDF 输出
- 编译生成的中间 PDF 保留在 %BUILD%。
- 编译成功后，将 %BUILD%/%MAIN%.pdf 复制到项目根目录。
- 根目录 PDF 命名为 %ROOT_PDF%。
- 最终提示中显示根目录 PDF 路径。

4. 字数统计
- 不生成 %BUILD%/wordcount.txt。
- 只生成 Markdown 格式报告：
  %BUILD%/wordcount.md
- 使用 %PERL_EXE% 执行 %TEXCOUNT_PL%。
- 新增 PowerShell 脚本：
  %WORDCOUNT_SCRIPT%
- compile.bat 调用该 PowerShell 脚本，传入：
  - Perl 路径
  - texcount.pl 路径
  - build 目录
  - 章节文件列表
- Markdown 报告应包含：
  - 生成时间
  - 统计工具
  - Summary 汇总表
  - By Chapter 分章统计表
  - Text、Headers、Captions、Combined total 四列
- Combined total = Text + Headers + Captions。

5. Git 忽略规则
- 更新 .gitignore。
- 忽略 %BUILD% 下大部分编译产物。
- 但反忽略 %WORDCOUNT_SCRIPT%，使其进入版本管理。
- 忽略根目录生成的 %ROOT_PDF%。
- 推荐规则：
  build/*
  !build/tools/
  build/tools/*
  !build/tools/wordcount-report.ps1
  00-Main.pdf
  *.aux
  *.bbl
  *.bcf
  *.blg
  *.fdb_latexmk
  *.fls
  *.idx
  *.ilg
  *.ind
  *.lof
  *.log
  *.lot
  *.out
  *.run.xml
  *.synctex.gz
  *.toc

6. Codex 忽略规则
- 新增或更新 .codexignore。
- 忽略 .git、build、图片、PDF、Office 文件和压缩包。
- 保留 .tex、.bib、.md、.bat、.ps1 等文本文件可供 Codex 读取。

7. 验证
- 运行 compile.bat。
- 确认根目录生成 %ROOT_PDF%。
- 确认 %BUILD% 中保留编译临时文件。
- 确认 %BUILD%/wordcount.md 生成。
- 确认不生成 %BUILD%/wordcount.txt。
- 确认 git status 中只显示应纳入版本管理的配置文件和工具脚本，不显示 PDF 和 build 编译产物。

下面几节对prompt中应该达到的几个关键目的做简单解读。

四、集中变量配置

为了让脚本更容易迁移到其他项目，建议把所有关键路径和项目参数集中放在 compile.bat 开头。

例如：

set "MIKTEX_BIN=E:/Program Files/MiKTeX/miktex/bin/x64"
set "PERL_BIN=E:/Strawberry/perl/bin"
set "PERL_EXE=E:/Strawberry/perl/bin/perl.exe"
set "TEXCOUNT_PL=E:/Program Files/MiKTeX/scripts/texcount/texcount.pl"

set "MAIN=00-Main"
set "BUILD=build"
set "ROOT_PDF=%MAIN%.pdf"
set "WORDCOUNT_SCRIPT=build/tools/wordcount-report.ps1"

set "CHAPTER_FILES=0-Preface.tex;1-Introduction.tex;2-LCM Application.tex;3-Theory.tex;4-Preform.tex;5-resin-processibility-characterization.tex;6-filling-simulation.tex;8-写在最后.tex"

这样以后迁移到其他项目时，主要只需要修改：

MAIN
CHAPTER_FILES
MIKTEX_BIN
PERL_EXE
TEXCOUNT_PL

而不需要在脚本正文中到处查找路径。

五、自动编译流程

自动编译脚本 compile.bat 的核心流程是：

xelatex
bibtex
xelatex
xelatex
生成 wordcount.md

其中：

xelatex 负责生成 PDF、目录、交叉引用等
bibtex 负责参考文献
后两次 xelatex 用于刷新引用、目录和参考文献
wordcount-report.ps1 负责生成 Markdown 字数报告

xelatex 推荐使用以下参数：

-interaction=nonstopmode
-file-line-error
-output-directory=build

这样即使出现普通警告，也不会频繁中断；同时错误信息会带有文件和行号，便于定位问题。

六、临时文件与 PDF 输出

LaTeX 编译过程中会生成大量中间文件，例如：

.aux
.log
.toc
.out
.bbl
.blg
.idx

这些文件统一放入：

build/

最终 PDF 则复制到项目根目录：

00-Main.pdf

这样根目录保持清爽，同时最终文档也方便直接打开。

七、BibTeX 路径处理

由于 .aux 文件被输出到了 build/，BibTeX 应当在 build/ 内运行。

否则可能出现找不到章节 .aux 文件的问题。

同时，参考文献数据库通常位于项目根目录，例如：

reference.bib

因此需要设置：

set "BIBINPUTS=.;..;%BIBINPUTS%"

这样 BibTeX 在 build/ 中运行时，也能找到上一级目录中的 .bib 文件。

八、字数统计报告

本方案不再生成 build/wordcount.txt，只生成 Markdown 报告：

build/wordcount.md

字数统计使用：

E:/Program Files/MiKTeX/scripts/texcount/texcount.pl

并通过 Strawberry Perl 执行：

E:/Strawberry/perl/bin/perl.exe

统计方式为：对每个章节文件分别运行 texcount，然后汇总为 Markdown 表格。

File	Text	Headers	Captions	Combined total
0-Preface.tex	1758	0	0	1758
1-Introduction.tex	3595	126	105	3826
2-LCM Application.tex	4450	169	115	4734

九、总结

通过 Codex 配置本地 MiKTeX 自动编译，可以把 LaTeX 长文档项目的编译流程固化为一个稳定、可迁移的脚本。

这个方案的核心优点是：

一键完成完整 LaTeX 编译
编译临时文件集中到 build/
最终 PDF 输出到根目录
自动生成 Markdown 字数报告
变量集中配置，方便迁移到其他项目
Git 和 Codex 忽略规则清晰

以后迁移到新项目时，只需要修改 compile.bat 顶部的变量配置即可快速复用：

MAIN
CHAPTER_FILES
MIKTEX_BIN
PERL_EXE
TEXCOUNT_PL

。