VSCode中pandoc命令找不到，需检查PATH与环境变量：插件不继承Shell的PATH，应通过pandoc.executablePath配置绝对路径，并启用--verbose日志定位问题，同时确保reference.docx含中文字体定义、mermaid-filter路径正确且有执行权限。
VSCode里pandoc命令找不到：检查PATH和环境变量
VSCode终端能运行pandoc --version，不代表插件就能调用它。插件默认不继承系统Shell的PATH，尤其在Windows上，GUI启动的VSCode往往看不到你手动配置的环境变量。
- 打开VSCode，按
Ctrl+Shift+P→ 输入“Developer: Toggle Developer Tools”，在Console里执行process.env.PATH，确认输出里是否包含Pandoc安装路径（如D:\Tools\Pandoc） - 如果没出现，别改系统PATH——直接在VSCode设置里搜
pandoc.executablePath，填入绝对路径，例如：D:\Tools\Pandoc\pandoc.exe（Windows）或/usr/local/bin/pandoc（macOS） - 注意斜杠方向：Windows下必须用反斜杠
\或双正斜杠//，单个/可能被误解析为转义符
导出失败但无报错信息：强制启用verbose模式
很多插件静默失败，根本原因被掩盖。你需要让Pandoc把每一步都打出来，才能定位是路径错、模板缺，还是编码崩了。
- 在VSCode的插件设置中，找到
pandoc.args配置项，添加--verbose参数 - 同时建议加上
--log=debug.log，日志会生成在当前工作目录，比弹窗提示更完整 - 常见线索：
Could not find reference.docx说明模板路径不对；Cannot decode byte指向UTF-8 BOM或GBK编码残留；Failed to run filter则大概率是mermaid-filter没装或路径未配
中文乱码/代码块变样：reference.docx模板必须带中文字体定义
不是Pandoc版本问题，也不是插件bug，而是reference.docx这个模板文件本身没声明东亚字体族。空模板或英文模板导出的Word，在Windows上默认用Calibri显示中文，必然成方框。
- 不要用
pandoc --print-default-data-file reference.docx生成的原始模板——它不含中文支持 - 下载一个已配置好的中文模板，比如
ref-zh.docx，确保其styles.xml里有类似这样的节点：<w:font w:eastAsia="Microsoft YaHei"/> - 在插件设置中指定
pandoc.referenceDoc为该文件的绝对路径，且路径中不能有中文或空格（哪怕模板名是ref-zh.docx，也别放在我的文档这种目录下） - 验证是否生效：导出后打开Word，选中一段中文，看字体下拉框是否显示“微软雅黑”或“思源黑体”——不是靠肉眼猜，要真点开看
Mermaid图不渲染/报filter错误：过滤器路径和权限常被忽略
插件调用mermaid-filter时失败，90%不是filter本身坏了，而是VSCode找不到它，或者没权限执行。
- 先确认filter已全局安装：
npm install -g @mermaid-js/mermaid-filter，然后在终端跑mermaid-filter --version看是否响应 - VSCode插件不会自动识别npm全局bin路径，必须显式配置
pandoc.filterPaths，填入node_modules/.bin所在目录（如C:\Users\用户名\AppData\Roaming\npm\node_modules\.bin） - Windows用户特别注意：如果用PowerShell作为默认终端，而filter是Node.js写的，需确保VSCode终端设置里
terminal.integrated.defaultProfile.windows没强制设为CMD——CMD对Node脚本支持差，容易卡在spawn阶段
