Laravel 11中Spatie PDF生成时Vite未运行丢失CSS样式问题

数据老陈

2026-6-14

问题排查与解决步骤

1. 修正TailwindCSS的内容扫描范围

生产构建时Tailwind会自动清除未使用样式，如果PDF视图文件没被纳入扫描范围，相关样式会被直接删掉。

修改tailwind.config.js，把PDF视图路径加入content数组：

export default {
  content: [
    "./resources/views/**/*.blade.php",
    "./resources/views/pdf/**/*.blade.php", // 替换为你实际的PDF视图目录
    "./app/Http/Controllers/**/*.php",
  ],
  // 其他配置项
}

修改后重新执行npm run build完成部署。

2. 使用绝对URL引入构建后的CSS

spatie/laravel-pdf的渲染引擎（如Chrome）无法解析相对路径的CSS文件，需用Laravel的资源生成函数输出完整绝对URL：

<link rel="stylesheet" href="{{ Vite::asset('resources/css/app.css') }}">

这个方法会自动适配本地开发和生产环境，指向正确的构建后文件，无需手动写哈希文件名。

如果直接指定构建文件，确保用asset()生成绝对路径：

<link rel="stylesheet" href="{{ asset('build/assets/app-Bq_2mYPq.css') }}">

3. 内联CSS到PDF视图

若外部CSS仍无法加载，可直接将构建后的CSS内容内联到PDF的<style>标签中：

<style>
{!! file_get_contents(public_path('build/assets/app-Bq_2mYPq.css')) !!}
</style>

注意确认服务器有该文件的读取权限，且文件名与实际构建后的哈希文件名一致。

4. 检查PDF渲染引擎的资源加载配置

确保spatie/laravel-pdf的渲染配置允许加载外部资源，以Chrome引擎为例：

// config/pdf.php 或生成PDF时的自定义配置
return [
    'default' => 'chrome',
    'engines' => [
        'chrome' => [
            'options' => [
                'no-sandbox' => true,
                'disable-gpu' => true,
                'allow-file-access-from-files' => true, // 允许加载本地静态资源
            ],
        ],
    ],
];