Sublime调用pandoc失败主因是PATH未生效或构建变量误用；需验证pandoc安装、修正环境变量、在.sublime-build中写死路径并正确引用${file}等变量，配合--reference-doc模板和中文渲染参数方可正常导出。
Sublime 调用 pandoc 失败：pandoc is not recognized
这不是 Sublime 的问题，而是它根本没找到 pandoc 可执行文件。Sublime 的构建系统不读取你终端里生效的 PATH（尤其 macOS/Linux 的 ~/.zshrc 或 Windows 安装时漏选 “Add to PATH”）。
- 先在终端运行
pandoc --version，有输出（≥3.0）才算真正装好 - Windows 用户检查安装 pandoc 时是否勾选了 “Add to PATH”；没勾就重装，或手动把
C:\Program Files\Pandoc\加进系统环境变量 - macOS 用
brew install pandoc后，路径通常是/opt/homebrew/bin/pandoc（Apple Silicon）或/usr/local/bin/pandoc（Intel），GUI 应用默认不加载这些路径 - 临时解法：在
Pandoc.sublime-build里写死全路径，比如："shell_cmd": "/opt/homebrew/bin/pandoc -o \"${file_path}/${file_base_name}.docx\" \"${file}\""
构建系统里 ${file} 和 ${file_path} 混用导致输出错位或空文件
Sublime 构建变量不是占位符模板，而是字符串拼接，拼错一个字符就崩。常见错误是把 ${file_base_name} 当成带扩展名的文件名，或者漏掉双引号导致含空格路径直接截断。
-
${file}是完整路径（如/Users/me/My Documents/note.md） -
${file_path}是目录路径（如/Users/me/My Documents），结尾不含斜杠 -
${file_base_name}是文件名不含扩展名（如note），不能用来做输入源——输入必须用${file} - 正确写法必须加双引号：
"shell_cmd": "pandoc \"${file}\" -o \"${file_path}/${file_base_name}.docx\"" - 如果输出目录和当前文件不在同一级，别硬改
${file_path}，直接写绝对路径更稳，比如\"/tmp/${file_base_name}.docx\"
导出 Word 排版简陋：标题无样式、无目录、中文字体糊成一团
默认生成的 .docx 是裸文档，pandoc 不自带 Word 样式。所谓“格式控制”，本质是靠 --reference-doc 注入一个已有 .docx 模板里的样式定义。
- 准备一个干净的 Word 文件（比如叫
template.docx），设置好标题 1/2/3、正文、引用样式，保存后放在固定路径（如~/Templates/template.docx） - 构建命令里加上参数：
--reference-doc=\"/Users/me/Templates/template.docx\" - 中文支持必须显式启用：加
--from=markdown+tex_math_dollars，否则 $a^2$ 类公式不渲染 - 如果用了引用（@smith2020），还得加
--filter=pandoc-citeproc，且确保references.bib在同目录或指定路径
插件 Pandoc.sublime-build 与 SublimeText-Pandoc 插件选哪个
纯手动配构建系统（Pandoc.sublime-build）比装插件更可控、更少埋坑。SublimeText-Pandoc 插件虽方便，但它的 config.json 里 pandoc_path 容易配错，且插件本身多年未更新，对 Sublime Text 4 的兼容性不稳定。
- 插件的
main.py是硬编码调用pandoc，不处理路径空格，也不传参给--reference-doc - 插件设置里若填错
pandoc_path（比如多了一个斜杠），整个命令静默失败，连错误都不报 - 构建系统能一眼看到完整命令，改参数、加过滤器、换模板都直接编辑 JSON，没有黑盒逻辑
- 真要用插件，务必去
Preferences → Package Settings → Pandoc → Settings – User手动补全"pandoc_path": "/opt/homebrew/bin/pandoc"
