VSCode中LaTeX格式化失败的根本原因是latexindent工具缺失、路径错误或Perl模块不全。该工具由LaTeX Workshop插件调用，依赖YAML::Tiny等Perl模块，需通过终端验证which/where命令及latexindent -v，并在settings.json中配置正确路径和模块安装。
VSCode 本身不格式化 LaTeX，真正干活的是 latexindent —— 它必须存在、可执行，且 Perl 模块齐全，否则点保存就弹出 “Formatting failed”。
latexindent 没装或路径不对是最常见原因
LaTeX Workshop 插件默认会去系统 PATH 里找 latexindent，但 TeX Live 安装后它不一定自动加入 PATH（尤其 macOS/Linux 的非交互式 shell 或 WSL 环境），Windows 则常因安装路径含空格或权限问题导致调用失败。
- 先在终端运行
which latexindent（macOS/Linux）或where latexindent（Windows），确认命令是否可访问 - 如果返回空，说明没装或不在 PATH；macOS 上
brew install latexindent可补全，Linux 用sudo tlmgr install latexindent - 若已存在但 VSCode 找不到，直接在
settings.json中硬编码路径："latex-workshop.formatting.latexindent.path": "/usr/local/bin/latexindent"（路径按实际替换） - Windows 用户注意：不要用带中文或空格的路径（如
C:\Program Files\...），建议解压到D:\tools\latexindent\bin\latexindent.exe并配置该绝对路径
Perl 模块缺失会让 latexindent 静默崩溃
latexindent 是 Perl 脚本，依赖 YAML::Tiny、File::HomeDir 等模块。缺一个，它就退出码 2，VSCode 只显示 “Formatting failed”，日志里却看不到 Perl 错误。
- 运行
latexindent -v查看版本和模块加载状态；若报错Can't locate YAML/Tiny.pm，说明模块缺失 - 用系统 Perl 安装（不是 conda 或 perlbrew 管理的）：
cpan YAML::Tiny File::HomeDir - macOS 上若用 Homebrew 安装的 Perl，需确保
latexindent调用的是它（检查#!/usr/bin/env perl头是否指向正确解释器） - WSL/Ubuntu 用户注意：
sudo apt install perl-modules-5.34不够，必须用cpan单独装，因为 TeX Live 自带的latexindent绑定的是系统 Perl
格式化行为受 .latexindent.yaml 控制，不是“一键变美观”
默认情况下 latexindent 只处理缩进和基础换行，不会重排 \begin{equation} 内部或调整注释位置——这些得靠项目级配置文件驱动。
- 在项目根目录放一个
.latexindent.yaml，内容可从 官方 defaultSettings.yaml 复制修改 - 关键开关如
defaultIndent: " "（两空格缩进）、modifyLineBreaks: 1（启用换行优化）、lookForYamlHeader: 1（支持文件头局部配置） - 想让公式环境自动换行对齐？加
environments:块，例如为align指定indentAfterBegin: 2 - VSCode 不会自动读取子目录下的
.latexindent.yaml，必须放在你设置的 LaTeX 根文件（%DOC%）所在目录
最容易被忽略的是：LaTeX Workshop 的 editor.formatOnSave 默认只对 latex 语言模式生效，而新创建的 .tex 文件有时被识别为 plaintext —— 手动点击右下角语言模式，选 “LaTeX” 再试一次格式化。
