Spatie Browsershot 项目环境配置指南

Spatie Browsershot 项目环境配置指南

browsershot Convert HTML to an image, PDF or string 项目地址: https://gitcode.com/gh_mirrors/br/browsershot

前言

Spatie Browsershot 是一个强大的 PHP 库，它通过 Node.js 和 Puppeteer 提供了网页截图和 PDF 生成功能。本文将详细介绍该项目的环境要求及配置方法，帮助开发者快速搭建运行环境。

核心依赖要求

要使用 Browsershot，您的系统必须满足以下基本要求：

1. Node.js 环境：需要 Node 22.0 (LTS) 或更高版本
2. Puppeteer 库：需要 v23.0 或更高版本

Puppeteer 是一个 Node 库，它提供了高级 API 来控制 Chromium 或 Chrome 浏览器，Browsershot 正是基于此实现网页渲染功能。

不同平台安装指南

MacOS 系统安装

在 MacOS 上安装 Puppeteer 非常简单：

# 项目本地安装
npm install puppeteer

# 全局安装（可选）
npm install puppeteer --location=global

Ubuntu 服务器安装

对于 Ubuntu 24.04 服务器，安装过程稍复杂：

# 检查 Node 和 npm 是否已安装
node -v && npm -v

# 全局安装 Puppeteer
sudo npm install -g puppeteer

# 安装 Chrome 浏览器
npx puppeteer browsers install chrome

# 安装必要的系统依赖
sudo apt update
sudo apt install libx11-xcb1 libxcomposite1 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6

这些依赖库是 Chromium 浏览器正常运行所必需的图形和系统组件。

自定义路径配置

在某些特殊环境下，可能需要手动配置各种路径：

1. 自定义 Node 和 npm 路径

Browsershot::html('Foo')
    ->setNodeBinary('/usr/local/bin/node')
    ->setNpmBinary('/usr/local/bin/npm');

2. 自定义环境变量路径

Browsershot::html('Foo')
    ->setIncludePath('$PATH:/usr/local/bin');

3. 自定义 Node 模块路径

Browsershot::html('Foo')
    ->setNodeModulePath("/path/to/my/project/node_modules/");

4. 自定义脚本路径

Browsershot::html('Foo')
    ->setBinPath("/path/to/my/project/my_script.js");

5. 自定义 Chrome/Chromium 路径

Browsershot::html('Foo')
    ->setChromePath("/path/to/my/chrome");

Chromium 高级配置

自定义启动参数

可以通过 addChromiumArguments 方法向 Chromium 传递自定义参数：

Browsershot::html('Foo')
    ->addChromiumArguments([
        'some-argument-without-a-value',
        'keyed-argument' => 'argument-value',
    ]);

参数传递规则：

| 数组示例 | 实际传递的参数 | |---------|--------------| | ['foo'] | --foo | | ['foo', 'bar'] | --foo --bar | | ['foo', 'bar' => 'baz'] | --foo --bar=baz |

解决字体渲染问题

在某些 Linux 发行版（如 CentOS）上，可能需要调整字体渲染参数：

Browsershot::html('Foo')
    ->addChromiumArguments([
        'font-render-hinting' => 'none',
    ]);

常见问题解决

1. 字体显示异常：尝试添加 font-render-hinting 参数
2. 依赖缺失：确保安装了所有列出的系统依赖
3. 路径问题：使用 setNodeBinary 等方法明确指定路径
4. 权限问题：全局安装时可能需要 sudo 权限

结语

正确配置环境是使用 Browsershot 的第一步。本文详细介绍了各种环境下的安装方法和配置选项，帮助开发者根据自身需求灵活调整。在实际使用中，如果遇到问题，可以参考这些配置选项进行排查和调整。

browsershot Convert HTML to an image, PDF or string 项目地址: https://gitcode.com/gh_mirrors/br/browsershot