snappy导出PDF样式丢失或布局错乱的根本原因是CSS路径不正确及wkhtmltopdf无法访问Laravel Mix编译后的资源；需内联CSS、禁用JS、设viewport、用绝对本地路径，并确保中文字体已安装。

snappy导出PDF时页面样式丢失或布局错乱

根本原因通常是CSS加载路径不正确，或者Laravel Mix编译后的资源路径在PDF渲染时无法被wkhtmltopdf访问。snappy底层调用wkhtmltopdf，它不走Web服务器路由，而是直接读取HTML字符串或本地文件，因此里的相对路径、asset()生成的URL（含域名）都会失效。

• 把CSS内联到HTML中，用file_get_contents()读取public/css/export.css并插入标签
• 避免使用asset()或url()，改用绝对本地路径：file://{{ public_path('css/export.css') }}
• 禁用JavaScript（snappy默认关闭JS执行），确保不依赖JS动态渲染内容
• 设置viewport meta和固定宽度容器，防止wkhtmltopdf按默认96dpi缩放失真

如何用snappy从Blade视图生成PDF并响应下载

关键不是“渲染视图再转PDF”，而是让snappy直接加载Blade渲染后的HTML字符串，并交由wkhtmltopdf处理。不能直接传视图名给SnappyPdfGenerator::loadView()就完事——得先确保视图里没有动态JS、异步请求、外部字体CDN等不可控因素。

• 在控制器中用view()->make('exports.invoice')->render()获取纯净HTML字符串
• 用SnappyPdfGenerator::loadHtml($html)->setOption('margin-top', 10)->setOption('page-size', 'A4')配置基础参数
• 调用download('invoice.pdf')触发浏览器下载；若需保存到storage，用output()获取二进制流再写入Storage::put('pdf/invoice.pdf', $pdfContent)
• 注意：中文需提前在CSS中指定支持中文字体，如font-family: "SimSun", "Microsoft YaHei", sans-serif，并确认系统已安装对应字体

use Barryvdh\Snappy\PdfGenerator;

$pdf = app(PdfGenerator::class);
$html = view('exports.invoice', ['order' => $order])->render();
$pdf->loadHtml($html)
    ->setOption('encoding', 'UTF-8')
    ->setOption('margin-top', 15)
    ->setOption('margin-bottom', 15)
    ->setOption('no-outline', true)
    ->setOption('quiet', false);

return $pdf->download('invoice.pdf');

snappy生成PDF空白页或报错Exit with code 1 due to network error

这是wkhtmltopdf最常见的失败类型，本质是它在离线环境下尝试加载外部资源（比如Google Fonts、CDN上的JS/CSS、甚至带http://的图片链接），而snappy默认不启用网络访问权限。

• 彻底移除所有https://或http://开头的资源引用，图片改用file://本地路径或Base64内联
• 检查错误日志：在setOption('quiet', false)开启后，$pdf->output()抛出异常时会附带wkhtmltopdf原始错误输出，里面常含具体失败URL
• 如果必须用网络资源，可加setOption('enable-local-file-access', true)（仅限可信环境），但不推荐用于生产
• Ubuntu部署时常见缺少字体或libfreetype，需手动安装：sudo apt-get install libfreetype6 libfontconfig1

Laravel 10+中snappy与Flysystem 3.x兼容性问题

新版Flysystem废弃了get()方法，而旧版snappy（如barryvdh/laravel-snappy 1.0）仍尝试调用它，导致Call to undefined method League\Flysystem\Filesystem::get()。

• 升级snappy到^1.2及以上版本，它已适配Flysystem 3
• 若无法升级，临时降级Flysystem到^2.5（需同步调整其他依赖）
• 检查config/snappy.php中的binary路径是否指向正确的wkhtmltopdf可执行文件，Laravel 10默认不再自动识别全局PATH
• Windows开发时注意路径分隔符，binary值应为'C:\wkhtmltopdf\bin\wkhtmltopdf.exe'而非正斜杠