必须先安装系统级wkhtmltopdf，再装barryvdh/laravel-snappy；Linux/macOS用包管理器安装，Windows下载官网安装包并配置PATH；验证用wkhtmltopdf --version；Laravel≥5.5需检查自动发现是否生效，手动注册服务提供者和PDF门面；PDF生成时资源须用绝对URL，中文字体需配置fontconfig并声明字体族。
Composer 安装 barryvdh/laravel-snappy 失败？先确认 wkhtmltopdf 是否就位
没装 wkhtmltopdf，光装 barryvdh/laravel-snappy 是白搭——它只是个 Laravel 封装层，真正干活的是系统级的 wkhtmltopdf 二进制程序。
常见错误现象：RuntimeException: The exit status code '127' says something went wrong，基本等于“找不到 wkhtmltopdf”。
- Linux/macOS：用包管理器装原生二进制（如
apt install wkhtmltopdf或brew install wkhtmltopdf），别用 npm 那套 - Windows：去 官网下载安装包，勾选「Add to PATH」，或手动把
wkhtmltopdf.exe所在目录加进系统环境变量 - 验证是否生效：终端直接运行
wkhtmltopdf --version，有输出才继续
laravel-snappy 的 Composer 安装与服务提供者注册
装包本身很简单，但 Laravel 5.5+ 自动发现机制有时会失效，尤其项目启用了缓存或旧版配置残留。
执行：composer require barryvdh/laravel-snappy
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
立即学习“前端免费学习笔记（深入）”；
- Laravel ≥5.5：一般自动注册
Barryvdh\Snappy\ServiceProvider，但建议仍检查config/app.php中providers数组是否含该行 - Laravel ≤5.4 或自动发现失败：手动加到
providers里，并加 facade 别名：'PDF' => Barryvdh\Snappy\Facades\SnappyPdf::class - 运行
php artisan config:clear，避免旧配置干扰
生成 PDF 时路径 404 或样式丢失？重点查 URL 和视图渲染上下文
wkhtmltopdf 是离线渲染，它不走 Laravel 的路由和中间件，所以相对路径、asset()、url() 生成的链接极容易 404。
- 静态资源（CSS/JS/图片）必须用绝对 URL，推荐改用
asset()+ 全局域名，比如https://yoursite.test/css/app.css - 避免在 PDF 视图中调用需登录态或 CSRF 的接口；如果必须请求后端数据，提前在控制器里取好，传给视图
- 测试技巧：先把 PDF 对应的 Blade 模板用浏览器打开，确认能正常加载所有资源，再交给 snappy
- 可临时启用调试：
PDF::setOption('debug-javascript', true)，看控制台报什么错
PDF 中文字体显示为方块？Linux/macOS 下 fontconfig 配置是关键
默认 wkhtmltopdf 不带中文字体，也不读取系统字体配置，单纯复制字体文件过去没用。
- Linux：确保已安装
fontconfig（apt install fontconfig），并把中文字体（如NotoSansCJK）放入/usr/share/fonts/，再运行fc-cache -fv - macOS：字体要装到「用户字体」或「系统字体」库，且用
fc-list :lang=zh确认能被识别 - CSS 中显式声明字体族：
body { font-family: "Noto Sans CJK SC", "PingFang SC", sans-serif; } - 避免用
@import引入 Google Fonts 等网络字体——wkhtmltopdf默认不联网
字体问题最耗时间，往往卡在配置没生效却以为是 PHP 层代码错了。确认 wkhtmltopdf 进程真能访问到字体，比调 Laravel 更优先。
