Sublime Text构建系统本质是shell命令封装而非转换器，.sublime-build文件仅包装终端可执行命令；常见问题源于PATH、路径空格、变量展开等环境差异，需确保pandoc路径正确、模板引用完整、JSON转XML用自定义Python脚本并配置绝对路径与path字段。
构建系统本质是 shell 命令封装，不是“转换器”
Sublime Text 的 .sublime-build 文件不自带任何转换逻辑，它只是把你在终端里能跑通的命令（比如 pandoc、python convert.py）包装成 Ctrl+B 可触发的形式。你卡在“没反应”或“报错”，90% 是因为命令本身在 Sublime 环境里根本执行不了——不是 Sublime 有问题，而是它调用外部工具时 PATH、路径空格、变量展开等细节和你的终端不一致。
pandoc 导出 Markdown 为 Word：必须加双引号 + 指定 template.docx
常见错误：pandoc is not recognized 或输出 .docx 打不开/样式全丢。前者是 pandoc 路径没被 Sublime 读到；后者是默认生成的文档没样式模板。
-
shell_cmd中所有含空格的路径必须用双引号包裹，例如"pandoc "${file}" -o "${file_path}/${file_base_name}.docx"" - 中文/公式支持需显式加参数：
--from=markdown+tex_math_dollars --filter=pandoc-citeproc - 排版靠
--reference-doc，不是 pandoc 自己决定的。准备一个设好标题样式的template.docx，路径写死或用${packages}变量引用 - macOS 用户注意：
brew install pandoc后真实路径常是/opt/homebrew/bin/pandoc，GUI 应用默认不读 shell profile，建议在shell_cmd里写全路径
JSON 转 XML：别信插件，用 Python 脚本最可控
所谓“一键 JSON to XML”插件基本失效或只做字符串包裹（比如把 {"a":1} 变成 <root><a>1</a></root>），不符合实际 XML 使用需求。可靠做法是写一个 Python 脚本，用 json 和 xml.etree.ElementTree 处理嵌套与数组，再通过构建系统调用。
- 脚本里避免硬编码路径，用
sys.argv[1]接收$file，输出文件名用os.path.splitext()改后缀 - 构建系统中
cmd字段必须写 Python 解释器绝对路径，尤其虚拟环境项目：Windows 示例["C:\myproject\venv\Scripts\python.exe", "-u", "convert_json_to_xml.py", "$file"] - 别漏
path字段——否则import xml.etree都可能失败，path值是目录（如C:myproject envScripts），不是可执行文件
构建文件放错位置 = 完全不生效
菜单 Tools → Build System 里看不到你新建的选项？不是命名问题，就是路径错了。Sublime 只扫描一个固定位置：Packages/User/。其他任何地方（项目根目录、桌面、Packages/MarkdownPreview/）都无效。
- Windows 正确路径：
%APPDATA%Sublime TextPackagesUser - macOS 正确路径：
~/Library/Application Support/Sublime Text/Packages/User/ - 文件名只能是英文+数字+下划线，后缀必须是
.sublime-build（不是.json或.sublime-build.txt） -
selector字段决定它出现在哪些文件类型菜单里，"source.gfm"表示只在 GitHub Flavored Markdown 文件中显示，"source.python"对应 .py 文件
复杂点在于：构建系统不处理语义，只转发命令。你指望它自动识别 JSON 结构差异、智能映射字段到 XML 元素层级——这超出了它的能力边界。真正要稳，就得自己写脚本控制逻辑，再用构建系统当个“快捷按钮”。
