Laravel Forge部署spatie/browsershot报browser.js模块找不到问题

问题背景 #

更新spatie/browsershot包后，部署到Laravel Forge时出现MODULE_NOT_FOUND错误，提示找不到browser.js，但vendor/spatie/browsershot/bin目录下只有browser.cjs，临时改名可恢复但非长久之计。

正规解决办法 #

1. 同步Browsershot配置中的脚本路径

首先发布Browsershot的配置文件（未发布过的话执行）：

php artisan vendor:publish --provider="Spatie\Browsershot\BrowsershotServiceProvider"

打开项目根目录下的config/browsershot.php，找到script_path配置项，将其值修改为：

'script_path' => base_path('vendor/spatie/browsershot/bin/browser.cjs'),

保存后，PHP端调用Browsershot时就会指向正确的.cjs入口文件。

2. 确保Node版本与依赖兼容

Browsershot新版本依赖的Puppeteer v19+要求Node.js 16.x及以上版本，确认Forge服务器上的Node版本符合要求：

node -v

如果版本过低，用Forge官方的升级脚本更新Node，避免版本不兼容导致的文件解析问题。

3. 清理缓存并重装依赖

执行以下命令彻底清理缓存并重新安装相关依赖：

# 清除Composer缓存
composer clear-cache
# 重新安装Browsershot
composer update spatie/browsershot
# 进入Browsershot目录重装Node依赖
cd vendor/spatie/browsershot
npm install

这能确保所有依赖文件都是最新且匹配的版本。

4. 修正部署脚本的权限设置

在Forge的部署脚本中，确保给正确的文件/目录添加权限：

# 给Puppeteer缓存目录添加可读权限
chmod -R o+rx ~/.cache/puppeteer
# 确保browser.cjs有执行权限
chmod +x vendor/spatie/browsershot/bin/browser.cjs

原因说明 #

Browsershot新版本将Node端入口脚本从.js改为.cjs（CommonJS模块格式），但默认配置或PHP端调用逻辑未同步更新，导致找不到文件。临时改名只是绕过了问题，修改配置路径才是根本解决方式，能避免后续包更新再次出现相同问题。

内容的提问来源于stack exchange，提问作者hyphen