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并插入<style></style>标签 - 避免使用
asset()或url()，改用绝对本地路径：file://{{ public_path('css/export.css') }} - 禁用JavaScript（snappy默认关闭JS执行），确保不依赖JS动态渲染内容
- 设置
viewportmeta和固定宽度容器，防止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'而非正斜杠
<div style="page-break-inside: avoid">控制分页。</div> 
