本文详解 wkhtmltopdf 中 --header-html 等模板参数的正确书写规范，重点解决因字符编码异常（如误入不可见扩展字符 à）导致的“Unknown long argument”错误，并提供可复用的命令示例与避坑指南。
本文详解 wkhtmltopdf 中 `--header-html` 等模板参数的正确书写规范，重点解决因字符编码异常（如误入不可见扩展字符 `à`）导致的“unknown long argument”错误，并提供可复用的命令示例与避坑指南。
在使用 wkhtmltopdf 将多个 HTML 模板（如主体页、页眉、页脚）合并生成 PDF 时，常见命令形如：
wkhtmltopdf --header-html header.html --footer-html footer.html --margin-top 25 --margin-bottom 25 body.html output.pdf
但许多用户升级系统或更换终端后，突然遇到类似错误：
Unknown long argument --header-htmlá
注意末尾的 á（Unicode U+00E1）——它并非合法连字符，而是由复制粘贴引入的不可见/乱码扩展字符（常源于富文本编辑器、网页、即时通讯工具或某些 IDE 的自动格式化）。wkhtmltopdf 严格解析参数，一旦检测到非 ASCII 连字符（如 —、– 或带重音的 á），便会报“Unknown long argument”。
✅ 正确做法：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- 手动键入所有参数，杜绝复制粘贴；
- 使用纯文本环境（如 VS Code 的纯文本模式、系统终端、nano/vim）编写命令；
- 检查 shell 历史记录中是否存在隐式编码污染（可用 cat -v your_command.sh 查看是否含 M-bM-^@M-^A 类似乱码）。
⚠️ 补充注意事项：
- --header-html 和 --footer-html 所引用的 HTML 文件需返回完整、独立的 HTML 片段（无需 ，但可含内联样式或简单 JS）；
- 页眉页脚模板中不支持外部 CSS/JS 文件（除非启用 --enable-local-file-access，但存在安全风险，慎用）；
- 若需动态内容（如页码），使用内置变量：[page]、[frompage]、[topage]、[webpage]、[section]；例如在 header.html 中写 第 [page] 页；
- Windows 用户注意路径分隔符，建议统一使用正斜杠 / 或双反斜杠 \，避免转义问题。
? 最佳实践建议：将命令封装为可执行脚本（如 gen-pdf.sh），并添加基础校验：
#!/bin/bash [ ! -f "body.html" ] && echo "错误：body.html 不存在" && exit 1 [ ! -f "header.html" ] && echo "错误：header.html 不存在" && exit 1 [ ! -f "footer.html" ] && echo "错误：footer.html 不存在" && exit 1 wkhtmltopdf --header-html "header.html" --footer-html "footer.html" --margin-top 20 --margin-bottom 25 --page-size A4 "body.html" "output.pdf"
只要确保参数字符串干净、编码为 UTF-8 且不含任何隐形符号，--header-html 等核心功能即可稳定工作——问题往往不在软件版本，而在输入过程的“看不见的细节”。
