使用说明
PDF2IMG-将PDF转换为图像
Go中的一个完整工具，用于将PDF页面渲染为PNG或JPG图像。包括CLI应用程序和MCP（模型上下文协议）服务器。
特性
- ✨ 高质量渲染 使用go-pdfium v1.17.2（基于pdfium）
- 🖼️ 多种格式：PNG和JPG
- 🎯 精细控制：可定制的DPI，可配置的页面范围
- 💻 完整的CLI：具有多个选项的命令行界面
- 🔌 MCP服务器：与模型上下文协议集成
- 📊 PDF信息：获取PDF文件元数据的命令
- 🚀 纯Go：无CGO，嵌入式WebAssembly，单个二进制文件（约18 MB）
- 🔒 跨平台：Windows、Linux、macOS
- 🌐 HTTP服务器：用于IIS集成的REST API微服务
安装
先决条件
- 转到1.26+
- 备注：不需要外部PDFium，所有内容都嵌入二进制文件中
源代码
git clone <repository-url>
cd pdf2img
go mod download
go build -o pdf2img ./cmd/pdf2img
全球安装
go install github.com/scopweb/mcp-go-pdf-to-img/cmd/pdf2img@latest
用法
CLI-基本转换
# Convert all pages to PNG
pdf2img -i document.pdf -o ./output
# Convert to JPG with custom DPI
pdf2img -i document.pdf -o ./output -f jpg -d 300
# Convert only pages 1-10
pdf2img -i document.pdf -o ./output --start 1 --end 10
# With custom prefix
pdf2img -i document.pdf -o ./output --prefix img_
CLI-获取PDF信息
pdf2img info document.pdf
输出：
PDF Information
===============
File: document.pdf
Pages: 25
Size: 2.50 MB
Width: 612.00 pt
Height: 792.00 pt
CLI选项
| 选项 | 简短 | 描述 | 默认 |
|---|---|---|---|
--input |
-i |
PDF路径（必填） | - |
--output |
-o |
输出目录 | . |
--format |
-f |
格式：png或jpg | png |
--dpi |
-d |
用于渲染的DPI | 150 |
--start |
- | 起始页（1-索引） | 0 （第一） |
--end |
- | 结束页（1个索引） | 0 （最后） |
--prefix |
- | 输出文件的前缀 | page_ |
--verbose |
-v |
详细输出 | false |
MCP服务器
pdf2img MCP服务器支持与Claude Desktop和其他支持模型上下文协议的系统集成。
使用Claude Desktop进行配置（推荐）
⚡ 快速指南：阅读 MCP_CLAUDESKTOP.md 获取分步说明。
摘要:
- 编译：
go build -o mcp-server.exe ./cmd/mcp-server - 编辑
claude_desktop_config.json（in%APPDATA%\Claude\) - 添加：
{
"mcpServers": {
"pdf2img": {
"command": "C:\\path\\to\\mcp-server.exe",
"args": ["--stdio"]
}
}
}
- 重新启动克劳德桌面
- 完成！现在您可以使用Claude的pdf2imig
有问题吗？ 阅读 MCP_钻孔.md 用于排除常见问题。
程序化使用
要在Go代码中使用MCP服务器：
package main
import (
"log"
"github.com/tu-usuario/pdf2img/mcp"
)
func main() {
server, err := mcp.NewMCPServer()
if err != nil {
log.Fatal(err)
}
defer server.Close()
// Use server.ExecuteTool() to execute tools
tools := server.GetTools()
for _, tool := range tools {
log.Printf("Available: %s", tool.Name)
}
}
可用的MCP工具
pdf_to_images
将PDF页面转换为PNG或JPG图像。
{
"pdf_path": "document.pdf",
"output_dir": "./output",
"format": "png",
"dpi": 150,
"start_page": 0,
"end_page": 0,
"prefix": "page_"
}
备注: start_page 和 end_page 值为0表示“所有页面”。
pdf_info
获取PDF信息（页面、大小、尺寸）。
{
"pdf_path": "document.pdf"
}
操作模式
MCP服务器支持两种模式：
- 标准 （Claude Desktop的默认设置）：
mcp-server --stdio - 超文本传输协议:
mcp-server --port 8080（用于测试）
更多示例请参见 示例.md.
HTTP服务器（REST API）
HTTP服务器为PDF到图像的转换提供了一个REST API，适用于与的IIS集成。NET应用程序。
快速开始
# Build the server
go build -o server.exe ./cmd/server
# Run with default settings (0.0.0.0:8080)
./server.exe
# Or with custom configuration
HTTP_PORT=8080 CONVERT_DEFAULT_DPI=200 ./server.exe
API终点
| 方法 | 端点 | 描述 |
|---|---|---|
| 得到 | /health |
健康检查，返回“正常” |
| 职位 | /api/v1/pdf/convert |
将PDF转换为图像（返回ZIP） |
| 职位 | /api/v1/pdf/info |
获取PDF元数据 |
转换请求
curl -X POST http://localhost:8080/api/v1/pdf/convert \
-F "file=@document.pdf" \
-F "dpi=150" \
-F "format=png" \
-F "start_page=1" \
-F "end_page=5"
参数：
file（必填）：PDF文件dpi（可选）：用于渲染的DPI（默认值：150）format（可选）：输出格式，“png”或“jpg”（默认：png）start_page（可选）：起始页码（默认值：1）end_page（可选）：结束页码（默认：最后一页）prefix（可选）：输出文件前缀（默认值：page_）retry（可选）：使用降低的DPI重试失败的页面（默认值：false）
答复： 包含转换图像的ZIP文件。
PDF信息请求
curl -X POST http://localhost:8080/api/v1/pdf/info -F "file=@document.pdf"
响应（JSON）：
{
"file": "document.pdf",
"pages": 25,
"file_size": "2.50 MB",
"width": 612,
"height": 792
}
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
HTTP_HOST |
0.0.0.0 |
服务器绑定地址 |
HTTP_PORT |
8080 |
服务器端口 |
HTTP_READ_TIMEOUT |
30s |
读取超时 |
HTTP_WRITE_TIMEOUT |
120s |
写入超时 |
HTTP_MAX_UPLOAD_SIZE |
200MB |
最大上传大小 |
LOG_LEVEL |
info |
日志级别（调试、信息、警告、错误） |
LOG_FORMAT |
text |
日志格式（文本、json） |
CONVERT_DEFAULT_DPI |
150 |
默认DPI |
CONVERT_DEFAULT_FORMAT |
png |
默认格式 |
CONVERT_DEFAULT_POOL_SIZE |
2 |
PDFium池大小 |
CONVERT_REFRESH_EVERY |
50 |
实例刷新之间的页面 |
CONVERT_RETRY_ON_FAILURE |
false |
重试失败的页面 |
项目结构
pdf2img/
├── cmd/
│ ├── pdf2img/
│ │ └── main.go # CLI application
│ ├── mcp-server/
│ │ └── main.go # MCP server
│ └── server/
│ └── main.go # HTTP REST API server
├── internal/
│ ├── config/
│ │ └── config.go # Server configuration
│ └── logging/
│ └── logger.go # Logging utilities
├── mcp/
│ └── server.go # MCP server implementation
├── pkg/
│ ├── converter/
│ │ └── converter.go # PDF to image conversion
│ └── splitter/
│ └── splitter.go # PDF page splitting
├── go.mod # Dependencies
└── README.md # This file
依赖项
- go pdfium v1.17.2 （Apache 2.0）：使用PDFium WebAssembly进行PDF渲染
- 眼镜蛇v1.10.1 （Apache 2.0）：CLI框架
- mark3labs/mcp版本0.43.0 （Apache 2.0）：官方MCP SDK
- wazero v1.9.0 （Apache 2.0）:Go的WebAssembly运行时（包含在Go-pdfium中）
例子
示例1：将整个文档转换为高分辨率
pdf2img -i book.pdf -o ./images -f jpg -d 300
创建以下文件： page_0001.jpg, page_0002.jpg等等。
示例2：仅提取前5页
pdf2img -i report.pdf -o ./thumbs --start 1 --end 5 --prefix thumb_
创建： thumb_0001.png, thumb_0002.png等等。
示例3:PDF信息
pdf2img info form.pdf
示例4：从Go代码开始
package main
import (
"log"
"github.com/tu-usuario/pdf2img/pkg/converter"
)
func main() {
conv, err := converter.New()
if err != nil {
log.Fatal(err)
}
defer conv.Close()
result, err := conv.Convert(&converter.ConvertOptions{
InputPath: "document.pdf",
OutputDir: "./output",
Format: "png",
DPI: 150,
})
if err != nil {
log.Fatal(err)
}
log.Printf("Successful: %d, Failed: %d", result.Successful, result.Failed)
}
技术
WebAssembly实现
此项目使用 使用WebAssembly访问pdfium v1.17.2，它提供：
- 纯Go：无CGO依赖关系，无需在主机上使用C编译器
- 单一二进制：所有内容都嵌入在一个可执行文件中（约18 MB）
- 跨平台：相同的二进制文件适用于Windows、Linux、macOS
- 演出：比多线程CGO版本快约2倍
- 安全：WebAssembly沙盒中的独立执行
为什么选择WebAssembly
选择WebAssembly而不是CGO是因为：
- ❌ CGO需要主机上的C编译器（在不同系统上有问题）
- ❌ go pdfium v1.12.0 CGO存在严重的兼容性错误
- ✅ WebAssembly更健壮、更便携
- ✅ 编译后不需要外部依赖
- ✅ 更好的资源隔离
📚 文档
公共文件
- QUICKSTART.md -5分钟后开始
- 示例.md -实际使用案例
- Developpent.md -发展指南
- 项目_结构.md -代码结构
- 贡献.md -如何做出贡献
- MCP_CLAUDESKTOP.md -Claude桌面集成
- MCP_钻孔.md -MCP故障排除
- 更改日志.md -更改历史记录
- 安全.md -安全策略
- 代码_OF_CONDUCT.md -行为守则
内部文件
有关维护人员和详细技术信息，请参阅 docs/README.md
故障排除
错误：“找不到PDF文件”
验证PDF路径是否正确：
ls -la document.pdf
错误：“初始化PDFium失败”
确保Go可以下载依赖项：
go mod download
go mod verify
图像以低分辨率显示
增加DPI值：
pdf2img -i document.pdf -o ./output -d 300 # Higher = better quality
处理速度慢
降低DPI以加快处理速度：
pdf2img -i document.pdf -o ./output -d 96
许可证
该项目使用Apache 2.0许可证下的go-pdfium。
贡献
欢迎捐款。拜托：
- 分叉项目
- 为您的功能创建分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add AmazingFeature') - 推到分支(
git push origin feature/AmazingFeature) - 打开拉取请求
路线图
- [x] ~~REST HTTP API ~~（实现为
cmd/server) - []水印支持
- []渲染图像的OCR
- []并行页面处理
- []渲染图像缓存
- []密码保护的PDF支持
