Latex本地编译

这份文档总结了在 macOS 上配置轻量化且功能完备的 LaTeX 环境（以支持 zjuthesis 浙江大学毕业论文模板为例）的全过程。它记录了从基础安装到 VS Code 深度集成的所有“坑点”与解决方案。避免Overleaf的编译时间限制。

一、 工具准备

为了节省空间（约 800MB，对比完整版 MacTeX 的 7GB+），我们采用 BasicTeX 方案。请严格按顺序执行：

1. 安装基础软件： 在终端执行以下命令（需先安装 Homebrew）：

   # 安装 BasicTeX 核心
   brew install --cask basictex
   

2. 配置系统全局路径（关键）： BasicTeX 安装后，系统默认找不到 xelatex 等命令。执行此命令将 TeX 工具同步到系统 /usr/local/bin，可根治 VS Code 报 ENOENT 错误：

   sudo /usr/local/texlive/2026basic/bin/universal-darwin/tlmgr path add
   

   (注：路径中 2026basic 请根据你安装的实际年份微调)

二、 环境优化与宏包补全 (Optimization & Packages)

1. 给包管理器换源： 默认源在国外，下载极慢且易断连。切换至清华大学镜像：

   sudo tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet
   

2. 一键补齐 zjuthesis 依赖包： BasicTeX 只有核心包，需手动安装论文模板必需的排版插件：

   sudo tlmgr install xecjk realscripts ms biblatex biber environ trimspaces \
   zhnumber unicode-math xstring enumitem caption fancyhdr geometry xcolor \
   graphicx titling tocloft datetime2 tracklang csquotes notoccite \
   algorithm2e algorithmicx listings xifthen ifmtarg mwe biblatex-gb7714-2015
   

3. 命令行手动编译（用于调试）：
   当 VS Code 报错信息不明确时，直接在项目根目录打开终端执行。如果这里能通，说明是插件配置问题；如果这里报错，说明缺宏包或语法有误：

4. 常规编译：使用 latexmk 自动处理参考文献和多次迭代。

latexmk -xelatex -outdir=out zjuthesis

• 彻底清理缓存：当由于字体修改或旧文件导致编译死循环时使用。

  latexmk -C -outdir=out
  

• “打地鼠”技巧： 若编译仍提示 XXX.sty not found，请先搜索再安装：

  • 搜索：tlmgr search --global --file XXX.sty
  • 安装：sudo tlmgr install <搜索到的包名>
  • 提示：若提示 example-image 找不到，请确保已安装 mwe 包。

三、 VS Code 插件配置 (Configuration)

1. 安装插件：在 VS Code 扩展市场搜索并安装 LaTeX Workshop。

2. 配置 settings.json： 在设置中搜索 latex-workshop.latex.tools，点击“在 settings.json 中编辑”。占位符说明：

   • %DOC%：指项目主文件全路径（如 zjuthesis.tex）。无论你在改哪个子章节，插件都会精准编译主入口，比 ${file} 更可靠。
   • %DIR%：主文件所在文件夹路径。
   • %OUTDIR%：编译产物输出目录（建议设为 %DIR%/out 以保持根目录整洁）。

   完整 JSON 配置模板：

   {
       "latex-workshop.latex.outDir": "%DIR%/out",
       "latex-workshop.latex.recipes": [{"name": "latexmk", "tools": ["latexmk"]}],
       "latex-workshop.latex.tools": [
           {
               "name": "latexmk",
               "command": "latexmk",
               "args": [
                   "-xelatex", // 关键：支持中文的编译引擎
                   "-synctex=1",
                   "-interaction=nonstopmode",
                   "-file-line-error",
                   "-outdir=%OUTDIR%",
                   "%DOC%"
               ]
           }
       ],
       "latex-workshop.latex.clean.command": "latexmk",
       "latex-workshop.latex.clean.args": ["-outdir=%OUTDIR%", "-auxdir=%OUTDIR%", "-c", "%DOC%"],
       "latex-workshop.view.pdf.viewer": "tab"
   }
   

四、 zjuthesis 模板避坑指南 (Template Tweaks)

在正式开始写论文前，请对 zjuthesis.tex 进行微调：

1. 中文字体修正（必做）： 在 \documentclass 选项中加入 fontset=macnew。

   • 原因：这会强制调用 macOS 系统自带的华文宋体/黑体，避免因找不到 Windows 字体导致的排版 Bug。

2. 严禁空行： 在 \documentclass[...] 的方括号内，参数之间绝对不能有空行。

   • 现象：若有空行会报 ! Paragraph ended before \@fileswith@ptions was complete。

3. 根目录清理： 若编译逻辑出现死循环或字体不更新，请先运行终端命令 latexmk -C -outdir=out 或点击编辑器里的垃圾桶图标清理缓存。

五、 VS Code 界面操作与指南 (Interface)

打开 .tex 文件后，点击左侧侧边栏的 “TeX 图标” 唤起面板：

1. Build LaTeX Project (编译)

   • 位置：面板顶部 COMMANDS 栏第一个按钮。
   • 快捷键：Cmd + Alt + B。
   • 原理：调用配置中的 latexmk 指令。
   • 注意：光标必须在 .tex 代码编辑区（不能在下方的 Output 输出面板），否则插件找不到 Root 文件。

2. View LaTeX PDF (预览)

   • 位置：View LaTeX PDF 按钮。
   • 快捷键：Cmd + Alt + V。
   • 效果：PDF 将在 VS Code 内部标签页（tab）实时预览。

3. Clean up (清理临时文件)

   • 图标：面板工具栏上的 垃圾桶。
   • 对应设置：执行 clean.command。编译出错时这是重启的第一步。

4. Structure (大纲视图)

   • 功能：展示论文目录结构，点击标题可实现文中快速跳转。

六、替换VSCode Latex Workshop自带的pdf浏览器

latex workshop自带的pdf浏览器打开很容易卡，建议使用vscode-pdf 插件

然后在vscode的侧边栏里选择一个pdf, 点击打开方式- 为*.pdf配置默认编辑器，选择vscode-pdf

制作ppt

【学习天地】都什么年代了，还在写传统PPT？使用Markdown与LLM协作快速制作幻灯片！ https://www.cc98.org/topic/6474082 复制本链接到浏览器或者打开【CC98】微信小程序查看~

Comments