pdfporter

pdfporter

输入文件，输出 PDF，也可以重塑 PDF。pdfporter 是 conv2pdf 转换服务的客户端：它接收你电脑上的文件 路径，发送文件进行转换，然后将结果写回原文件所在 位置。Office 文档、电子表格、演示文稿、图像、电子 书、PostScript 和 HTML 文件都会转换为 PDF；PDF 会 转换为 Word 文档或逐页图像；还可以合并、拆分、提取 页面、旋转、编号、添加水印、压缩、设置密码保护和解锁 PDF。

配置

• CONV2PDF_API_KEY（调用时必需）— 在 conv2pdf 控制面板的 Developer 选项卡中创建。每次请求都会通过 Authorization: Bearer <key> 发送。没有密钥时，服务 仍会启动并列出其工具；调用任何工具都会失败，并显示 如何设置密钥的说明。
• CONV2PDF_API_URL（可选）— API 基础 URL。默认为 https://api.conv2pdf.com/v1。
• CONV2PDF_TIMEOUT_MS（可选）— 每个请求的超时时间， 单位为毫秒。默认为 120000，因为转换可能确实需要 大约一分钟。

工具

• convert_to_pdf — 根据文件扩展名将文件转换为 PDF： Word、Excel、PowerPoint、OpenDocument、Apple Pages、 RTF、TXT 和 CSV 文件通过 office-to-pdf 转换；PNG、JPG、 WebP、GIF 和 TIFF 图像通过 image-to-pdf 转换；HEIC/HEIF 照片通过 heic-to-pdf 转换；EPUB 通过 epub-to-pdf 转换； PS/EPS 通过 ps-to-pdf 转换；HTML 通过 html-to-pdf 转换。 未知扩展名会在本地导致失败，不会发送请求。
• convert_url_to_pdf — 根据公开网页的地址将其渲染为 PDF。它始终需要提供 output_path，因为没有输入文件可供 将结果写入其所在位置。
• convert_heic_to_jpg — 将 iPhone HEIC 或 HEIF 照片转换为 JPG。
• convert_pdf_to_word — 将含有真实文本的 PDF 转换为可编辑的 DOCX 文档。打开受保护的 PDF 时，请传入 password。
• convert_pdf_to_images — 每页生成一张 PNG（默认）或 JPG 图像，并打包在 ZIP 文件中返回。
• merge_pdfs — 按 paths 中给出的顺序，将 2 到 20 个 PDF 合并为一个文件。
• extract_pdf_pages — 将 ranges 中列出的页面（例如 1-5,7,10-12）按书写顺序复制到新的 PDF 中。
• split_pdf — 每页生成一个 PDF，并打包在 ZIP 文件中。
• rotate_pdf — 将每一页旋转 rotation 指定的角度：90、180 或 270 度。
• add_page_numbers — 为页面编号，格式为“3 / 12” （format: "full"，默认）或“3” （format: "simple"），位置可选 position：底部居中 （默认）、底部左侧或底部右侧。
• add_watermark — 在每一页上加盖最多 50 个字符的 text。
• compress_pdf — 减小文件大小；quality 可设为 low、medium （默认）或 high，并将图像分辨率设为 72、150 或 300 DPI。
• protect_pdf — 设置新的 password（6 到 64 个字符），并可通过 prevent_print 和 prevent_copy 禁止打印或复制。
• unlock_pdf — 移除你知道的密码（将其作为 password 传入）， 或移除打印和复制限制。
• get_quota — 原样返回 API 密钥对应的套餐、用量和限额。

大多数 PDF 阅读工具都接受可选的 password，用于打开受保护的 PDF； 处理结果不带密码。

转换的行为

1. 输入文件会在本地读取，并以 multipart/form-data 格式 POST 到 <base>/convert/<api-tool>； 文件放在 file 字段中，工具的字段则作为字符串字段传递。
2. 收到 HTTP 429 或 503 时，服务端会等待 API 给出的延迟时间（Retry-After 标头；否则使用正文中的 retry_after 秒数），然后重试；最多重试两次，且仅当延迟时间不超过 30 秒时重试。
3. 转换响应包含 job_id 和相对路径的 download_url；结果会从 API 来源下载并写入磁盘，随后尽力从服务中删除该任务。

结果不会被覆盖。默认情况下，输出文件与输入文件位于同一目录：转换会替换扩展名（report.docx 会生成 report.pdf）；PDF 操作会添加后缀（compress_pdf 会将 report.pdf 生成为 report-compressed.pdf，convert_pdf_to_images 会生成 report-images.zip，依此类推）；合并操作则会在第一个输入文件所在目录生成 merged.pdf。如果目标名称已被占用，会在扩展名前依次添加 (2)、 (3)……，直到找到可用名称。若指定了 output_path，在发送任何内容之前，若该路径下已存在文件，则会拒绝操作。

转换成功后会返回 JSON 摘要： {"job_id": ..., "output_path": ..., "size_bytes": ...}， 如果服务响应中包含 quota 对象，也会一并返回。get_quota 会原样返回服务的响应正文。

错误：非 2xx 响应会在正文包含 error 代码时返回 conv2pdf error: <error>，否则返回 conv2pdf error: HTTP <status>；无法访问 API 时返回 conv2pdf unreachable。

CLI

每个工具都是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/pdfporter convert_to_pdf '{"path":"report.docx"}'
npx @reneturcios/pdfporter convert_url_to_pdf '{"url":"https://example.com/article","output_path":"article.pdf"}'
npx @reneturcios/pdfporter convert_heic_to_jpg '{"path":"IMG_0001.heic"}'
npx @reneturcios/pdfporter convert_pdf_to_word '{"path":"report.pdf"}'
npx @reneturcios/pdfporter convert_pdf_to_images '{"path":"report.pdf","format":"jpg"}'
npx @reneturcios/pdfporter merge_pdfs '{"paths":["a.pdf","b.pdf"]}'
npx @reneturcios/pdfporter extract_pdf_pages '{"path":"report.pdf","ranges":"1-5,7,10-12"}'
npx @reneturcios/pdfporter split_pdf '{"path":"report.pdf"}'
npx @reneturcios/pdfporter rotate_pdf '{"path":"scan.pdf","rotation":90}'
npx @reneturcios/pdfporter add_page_numbers '{"path":"report.pdf","position":"bottom-right"}'
npx @reneturcios/pdfporter add_watermark '{"path":"contract.pdf","text":"CONFIDENTIAL"}'
npx @reneturcios/pdfporter compress_pdf '{"path":"big.pdf","quality":"low"}'
npx @reneturcios/pdfporter protect_pdf '{"path":"confidential.pdf","password":"secret123","prevent_print":true}'
npx @reneturcios/pdfporter unlock_pdf '{"path":"protected.pdf","password":"secret123"}'
npx @reneturcios/pdfporter get_quota '{}'
npx @reneturcios/pdfporter --version

退出代码：成功时为 0，运行时错误时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/pdfporter mcp

MCP 客户端配置：

{
  "mcpServers": {
    "pdfporter": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pdfporter", "mcp"],
      "env": {
        "CONV2PDF_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/pdfporter
docker run --rm ghcr.io/cloudcorprecords/pdfporter get_quota '{}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios