推荐使用 homebrew 安装 pandoc：先安装 homebrew，再执行 brew install pandoc，最后用 pandoc --version 验证；若命令未识别，需检查并手动配置 path，如 export path="/usr/local/bin:$path" 并 source ~/.zshrc。
如果您希望在 macOS 系统上部署 Pandoc 文档转换工具，但遇到安装失败、命令不可识别或版本过旧等问题，则可能是由于安装方式不匹配系统环境或 PATH 配置缺失。以下是针对 macOS 的多种可靠安装路径及对应验证方法：
一、使用 Homebrew 安装（推荐大多数用户）
Homebrew 是 macOS 上最主流的包管理器，能自动处理依赖、更新与路径注册，安装后 pandoc 命令可直接在任意终端会话中调用。
1、若尚未安装 Homebrew，先在终端中执行以下命令安装：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2、安装完成后，运行：
brew install pandoc
3、验证是否生效：
pandoc --version
如输出类似 pandoc 3.5.1 的版本号，说明安装成功且已纳入系统 PATH。
二、下载官方 PKG 安装包（无需命令行基础）
该方式提供图形化安装流程，适合不熟悉终端操作的用户，安装程序会自动将 pandoc 可执行文件复制至 /usr/local/bin 并尝试配置 shell 环境变量。
1、访问 Pandoc 官方 GitHub Releases 页面：
https://github.com/jgm/pandoc/releases
2、向下滚动至 Assets 区域，找到以 pandoc-*.pkg 结尾的文件（例如 pandoc-3.5.1-macOS.pkg）
3、双击下载的 .pkg 文件，按提示完成安装（需输入管理员密码）
4、打开新终端窗口，执行：
which pandoc
若返回 /usr/local/bin/pandoc，表示路径已就绪；否则需手动添加路径（见后续步骤）
三、通过 MacPorts 安装（适用于已有 MacPorts 生态的用户）
MacPorts 是另一套成熟的 macOS 开源软件分发系统，其安装的 pandoc 默认置于 /opt/local/bin，需确保该路径已加入 shell 配置文件。
1、若未安装 MacPorts，前往 https://www.macports.org/install.php 下载并安装对应 macOS 版本的 .pkg
2、安装完成后，在终端中运行：
sudo port selfupdate
3、执行安装命令：
sudo port install pandoc
4、确认安装位置：
port contents pandoc | grep bin/pandoc
5、如输出为 /opt/local/bin/pandoc，请检查 ~/.zshrc 或 ~/.bash_profile 中是否包含：
export PATH="/opt/local/bin:$PATH"
四、手动配置 PATH（解决“command not found”问题）
无论采用上述哪种安装方式，若终端提示 zsh: command not found: pandoc，则表明 shell 无法定位可执行文件，必须显式声明其所在目录。
1、先确认 pandoc 实际安装路径，尝试以下任一命令：
find /usr -name pandoc 2>/dev/null | head -n1
ls -l /usr/local/bin/pandoc /opt/local/bin/pandoc 2>/dev/null
2、根据查得路径（如 /usr/local/bin/pandoc），编辑当前 shell 配置文件：
nano ~/.zshrc
3、在文件末尾新增一行：
export PATH="/usr/local/bin:$PATH"
4、保存退出后，立即加载配置：
source ~/.zshrc
5、再次运行：
pandoc --version
五、验证安装与基础转换测试
安装完成后的关键动作是执行一次最小闭环测试，确认解析器、输出器及默认模板均正常加载，避免因缺失 LaTeX 引擎导致 PDF 转换失败等隐性问题。
1、在终端中创建临时 Markdown 内容：
echo "# 测试文档" > test.md
2、执行 HTML 格式转换：
pandoc test.md -o test.html
3、检查输出文件是否存在且非空：
ls -lh test.html && head -n5 test.html
若生成的 test.html 包含 测试文档
，说明核心转换链路已通。
