本文详解 OCRmyPDF Docker 容器因冗余命令参数导致“unrecognized arguments”报错的根本原因与修复方案，重点说明 docker run 启动时 CMD 与 ENTRYPOINT 的协作机制，提供可直接复用的挂卷命令、Shell 封装脚本及生产级注意事项。
本文详解 ocrmypdf docker 容器因冗余命令参数导致“unrecognized arguments”报错的根本原因与修复方案，重点说明 `docker run` 启动时 `cmd` 与 `entrypoint` 的协作机制，提供可直接复用的挂卷命令、shell 封装脚本及生产级注意事项。
OCRmyPDF 的官方 Docker 镜像（如 jbarlow83/ocrmypdf-alpine）采用 ENTRYPOINT ["ocrmypdf"] 的设计模式——这意味着镜像已将 ocrmypdf 命令设为容器默认入口程序。当你在 docker run 命令中显式再次写入 ocrmypdf（例如 docker run ... ocrmypdf --rotate-pages input.pdf output.pdf），Docker 会把整个命令行拼接为：
ocrmypdf ocrmypdf --rotate-pages input.pdf output.pdf
此时，第一个 ocrmypdf 被识别为子命令，而后续的 --rotate-pages 和文件路径则被错误地传给该“子命令”，最终触发 unrecognized arguments 错误——正如你日志中出现的 64ee37a6fc66cf591ce4a35f-1.png_OCR.pdf 被当作非法参数解析。
✅ 正确做法：省略显式的 ocrmypdf 命令名，只传参数
# ✅ 正确：仅传递 ocrmypdf 所需的参数（无前置 'ocrmypdf'） docker run --rm \ -v "$(pwd)/pdf:/data" \ jbarlow83/ocrmypdf-alpine \ --rotate-pages \ --deskew \ --output-type pdfa \ /data/input.pdf \ /data/output.pdf
若使用命名卷（如你的 pdf-tools-data-volume），同样遵循该原则：
# ✅ 正确：挂载卷 + 仅传 OCR 参数 docker run --rm \ -v pdf-tools-data-volume:/work:rw \ jbarlow83/ocrmypdf-alpine \ --rotate-pages \ /work/64ee36779438c74174f123e9-1.png \ /work/64ee36779438c74174f123e9-1.png_OCR.pdf
? 提示：可通过 docker inspect jbarlow83/ocrmypdf-alpine 查看镜像元数据确认：
"Config": {
"Entrypoint": ["ocrmypdf"],
"Cmd": null
}这表明所有参数均直接交由 ocrmypdf 解析，无需二次封装。
? 进阶建议：封装为可复用脚本
为避免每次手动输入冗长命令，推荐创建轻量级 Shell 别名或脚本：
# ~/.bashrc 或 ~/.zshrc 中添加 alias docker-ocr='docker run --rm -i -v "$(pwd):/data" jbarlow83/ocrmypdf-alpine' # 使用时（自动映射当前目录为 /data） docker-ocr --rotate-pages --l eng /data/in.pdf /data/out.pdf
⚠️ 注意事项：
-
路径必须为容器内绝对路径：挂载后，宿主机
/path/to/pdf→ 容器内/data，所有参数中的文件路径须以此为根； -
权限问题：Alpine 镜像以非 root 用户（UID 1001）运行，确保挂载目录对 UID 1001 可读写（Linux/macOS 下可
chmod -R a+rw或chown -R 1001:1001）； -
Windows 用户注意：Docker Desktop 默认仅共享
C:\Users，若 PDF 不在此路径下，需在 Docker Desktop 设置中启用对应驱动器共享； -
批量处理：可结合
find+xargs实现目录级 OCR，但需注意单容器单任务特性，勿在一条命令中传入多个输出文件（OCRmyPDF 不支持通配符批量输出）。
总结：OCRmyPDF 的 Docker 化本质是「将 CLI 工具容器化」，而非「运行一个带 Web 服务的长期容器」。理解 ENTRYPOINT 语义、消除冗余命令词、严格匹配挂载路径，即可零配置跑通生产级 PDF 文字识别流水线。
