本文详解 wkhtmltopdf 中 --header-html 和 --footer-html 参数的正确用法，重点解决因字符编码异常（如误入不可见扩展字符 à）导致的“Unknown long argument”报错问题，并提供可复用的命令示例与避坑指南。
本文详解 wkhtmltopdf 中 `--header-html` 和 `--footer-html` 参数的正确用法，重点解决因字符编码异常（如误入不可见扩展字符 `à`）导致的“unknown long argument”报错问题，并提供可复用的命令示例与避坑指南。
在使用 wkhtmltopdf 将 HTML 模板（如正文、页眉、页脚三部分）合并生成 PDF 时，一个常见却极易被忽视的问题是：命令行参数看似正确，却报出类似 Unknown long argument --header-htmlá 的错误。注意末尾的 á（或 à、â 等变音符号）——它并非你有意输入的字符，而是隐藏的 UTF-8 编码乱码残留，通常由复制粘贴引发。
根本原因在于：某些编辑器、网页、即时通讯工具或终端在复制含短横线（-）的命令时，可能将 ASCII 连字符 -（U+002D）错误替换为形似但语义不同的 Unicode 字符，例如：
- –（en dash, U+2013）
- —（em dash, U+2014）
- ´ 或 à（重音符号，U+00B4 / U+00E0）
wkhtmltopdf 严格校验参数名，仅接受标准 ASCII 连字符组成的 --header-html，一旦检测到非 ASCII 字符（如 --header-htmlá），即判定为非法长参数并中止执行。
✅ 正确写法（纯 ASCII）：
立即学习“前端免费学习笔记（深入）”；
wkhtmltopdf \ --header-html header.html \ --footer-html footer.html \ body.html \ output.pdf
⚠️ 错误写法（常见陷阱）：
# ❌ 复制自网页/微信/Word 后出现隐形字符 wkhtmltopdf --header-htmlá header.html ... # 报错！ # ❌ 使用中文输入法下的短横（全角或特殊符号） wkhtmltopdf —header-html header.html ... # 报错！
? 关键实践建议：
- 永远手动键入参数：避免从浏览器、文档或聊天窗口直接复制命令；
- 检查终端编码：确保 shell（如 bash/zsh）使用 UTF-8，但输入时禁用智能引号和自动更正（尤其 macOS 的“智能连字符”功能需关闭）；
- 验证字符纯度：在 Linux/macOS 下可用 echo "--header-html" | hexdump -C 查看是否全为 2d 2d 68 65 61 64 65 72 2d 68 74 6d 6c（即 ASCII - 和字母）；
- 封装为脚本：将常用命令写入 .sh 脚本文件（用 Vim/VS Code 等纯文本编辑器保存为 UTF-8 无 BOM），杜绝临时粘贴风险；
- 启用调试模式：添加 --debug-javascript 或先运行 wkhtmltopdf --help | grep header 确认参数是否存在且拼写准确。
? 补充提示：页眉/页脚 HTML 文件需满足基本规范——
- 必须为完整 HTML 片段（含 或至少 ）；
- 内联样式优先（外部 CSS 可能不加载）；
- 支持 page、frompage、topage 等内置变量，例如：
Page [page] of [topage]。只要确保参数字符串 100% 由标准 ASCII 构成，--header-html 和 --footer-html 即可稳定协同工作，精准合成专业级 PDF 文档。
