KnpSnappyBundle

在 Symfony 中一键将 HTML 转为 PDF 和图片

KnpSnappyBundle 是一个 Symfony 框架的集成包，用于在 PHP 项目中轻松生成 PDF 和图片。它封装了 KnpSnappy 库，后者基于 WebKit 引擎（通过 wkhtmltopdf/wkhtmltoimage 工具）将 HTML 内容转换为 PDF 或图片。该包解决了 PHP 后端生成高质量文档和图像的需求，无需依赖外部服务。核心能力包括：提供简单的服务调用接口，支持配置多个转换选项（如页面大小、边距、缩放等），支持从 URL 或字符串生成 PDF，以及将 HTML 转换为 PNG/JPEG 图片。它简化了 Symfony 中的集成流程，通过依赖注入和配置自动注册服务，开发者只需几行代码即可完成转换。

开源 free 图像生成

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1246

维护状态低维护

是否开源是

定价模式 free

项目数据

分类图像生成

开发团队KnpLabs

所属国家

官网地址http://knplabs.com

GitHubhttps://github.com/KnpLabs/KnpSnappyBundle

定价模式free

价格说明开源项目，MIT许可证，完全免费，无付费版本。

访问状态

是否开源是

开源协议MIT

主要语言PHP

技术栈/模型hacktoberfest,html-to-image,html-to-pdf,image-generation,pdf-generation,php,symfony,symfony-bundle

GitHub 星标★ 1246

30天Star增速

HF 下载量

上线时间2010-06-27 00:00:00

最近更新2026-09-03 00:00:00

维护状态低维护

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数5

使用教程

难度：入门约 10 分钟部署方式：库/依赖 4 步

环境要求

PHP 环境（项目为 PHP / Symfony 项目）
已安装 Composer 包管理工具
Symfony 项目已可通过 Flex 或手动方式注册 Bundle
系统已安装 wkhtmltopdf 与 wkhtmltoimage 可执行文件（Snappy 依赖该转换工具）

安装与启动步骤

1安装 Bundle

在 Symfony 项目根目录执行 Composer 命令，安装 KnpSnappyBundle 依赖包。
```
composer require knplabs/knp-snappy-bundle
```
2注册 Bundle

如果项目未使用 Flex 自动注册，需在 config/bundles.php 的返回数组中手动加入该 Bundle，环境设为 all。
3配置转换服务

按需在 config/packages/knp_snappy.yaml 中配置 pdf 与 image 服务的启用状态、二进制路径与选项。
4确认二进制可用

确认 wkhtmltopdf / wkhtmltoimage 已安装且路径与配置一致；Windows 下路径需按 README 示例加双引号并转义反斜杠。

关键配置

配置项	必填	说明	示例
`knp_snappy.pdf.enabled`	否	是否启用 PDF 生成服务	`true`
`knp_snappy.pdf.binary`	否	wkhtmltopdf 可执行文件的路径	`/usr/local/bin/wkhtmltopdf`
`knp_snappy.pdf.options`	否	PDF 转换选项数组，如页面大小、边距、缩放等	`[]`
`knp_snappy.image.enabled`	否	是否启用图片生成服务	`true`
`knp_snappy.image.binary`	否	wkhtmltoimage 可执行文件的路径	`/usr/local/bin/wkhtmltoimage`

如何确认成功

执行 composer require 后看到依赖安装成功，且 config/bundles.php 中已包含 KnpSnappyBundle，配置文件无语法错误。

常见问题

Q：页面里用 JavaScript 渲染会出问题吗？

A：会。wkhtmltopdf 对 ES6 API 不完全兼容，可能出现渲染异常；README 给出的解决办法是提供 polyfill 来补齐现代 ES6 API 的差异。

Q：不使用 Symfony Flex 怎么办？

A：需要手动注册 Bundle，在 config/bundles.php 的返回数组中加入 KnpBundleSnappyBundleKnpSnappyBundle::class => ['all' => true]。

Q：如何更换转换工具的可执行文件路径？

A：修改 config/packages/knp_snappy.yaml 中对应服务的 binary 配置项即可，例如把 pdf.binary 指向 /usr/local/bin/wkhtmltopdf。

Q：Windows 下 binary 路径怎么写？

A：README 示例使用双引号包裹整个路径并转义反斜杠，例如 "C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe"。

注意事项

README 未给出生成 PDF/图片的具体调用代码示例，实际使用请参考 KnpSnappy 库的文档。
pdf 与 image 两个服务都可通过 enabled 配置单独关闭。
README 节选中配置示例被截断，请以官方仓库中的完整配置文件为准。

核心亮点

与 Symfony 深度集成，通过服务容器即可调用，无需手动配置
基于 WebKit 渲染，转换质量高，支持复杂 CSS 布局
支持丰富的转换选项，可灵活控制输出格式和样式

不足之处

依赖外部二进制 wkhtmltopdf，部署环境需额外安装
WebKit 引擎较老，对现代 CSS 特性支持有限
文档/社区待观察

适用场景

生成发票、报告等 PDF 文档
将网页截图保存为图片
批量生成证书或标签

替代项目

Dompdf、Tcpdf、Snappy

项目介绍

KnpSnappyBundle 是图像领域的开源项目，由 KnpLabs 开发，2010 年首次发布。

在全站 12,961 个收录项目中，它的 GitHub 星标数（1,246）位列前 30%，在图像分类的 837 个项目里位列前 14%。

项目已超过三个月没有代码更新，维护节奏明显放缓，最近一次代码更新于 2026-09-03。MIT许可证，完全免费，无付费版本。

它主要面向的使用场景是：生成发票、报告等PDF文档。同类可对比的替代方案包括 Dompdf、Tcpdf、Snappy。

上一篇：AmazingZImageWorkflow

下一篇：StereoDiffusion