Debian无桌面环境下PM2启动Puppeteer脚本遇X服务器缺失问题求助

1. 安装并配置基础X服务器与窗口管理器 #

无桌面环境缺少X服务器支持，先安装Xorg和轻量窗口管理器Openbox（用于管理窗口全屏显示）：

• 执行安装命令：

apt update && apt install xorg xinit openbox

• 配置Xorg强制匹配屏幕分辨率：
  创建/编辑/etc/X11/xorg.conf，添加以下内容（替换分辨率为你的屏幕实际参数，可通过cvt 宽 高命令获取对应模式）：

Section "Monitor"
    Identifier "Monitor0"
    Option "PreferredMode" "1920x1080"
    Option "DPMS" "off" # 禁用屏幕自动休眠
EndSection

Section "Screen"
    Identifier "Screen0"
    Device "Card0"
    Monitor "Monitor0"
    SubSection "Display"
        Modes "1920x1080"
        Virtual 1920 1080 # 强制锁定分辨率
    EndSubSection
EndSection

2. 设置X服务器开机自动启动 #

• 创建X启动脚本/usr/local/bin/start-x.sh：

#!/bin/bash
export DISPLAY=:0
# 启动Openbox并绑定到:0显示端口，关闭光标（可选）
startx /usr/bin/openbox -- :0 -nocursor

• 赋予脚本执行权限：

chmod +x /usr/local/bin/start-x.sh

• 创建systemd服务实现开机自启：
  新建/etc/systemd/system/x-server.service文件：

[Unit]
Description=Start X Server for Chrome Display
After=network.target

[Service]
User=root # 或你运行Node脚本的用户，需确保该用户有X访问权限
ExecStart=/usr/local/bin/start-x.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

• 启用并启动服务：

systemctl daemon-reload && systemctl enable x-server.service && systemctl start x-server.service

3. 配置PM2进程的DISPLAY环境变量 #

方法1：直接在启动命令中指定 #

修改你的PM2启动命令，添加DISPLAY=:0环境变量：

pm2 start npm --name "Worker" --exp-backoff-restart-delay=100 --env DISPLAY=:0 -- start

方法2：通过PM2配置文件设置 #

• 导出PM2配置文件：

pm2 ecosystem

• 编辑生成的ecosystem.config.js，在apps数组中添加环境变量：

module.exports = {
  apps : [{
    name: "Worker",
    script: "npm",
    args: "start",
    env: {
      DISPLAY: ":0"
    },
    exp_backoff_restart_delay: 100
  }]
}

• 启动并保存配置：

pm2 start ecosystem.config.js
pm2 save
pm2 startup # 按照终端提示执行生成的命令，设置PM2开机自启

方法3：在Node脚本中强制设置DISPLAY #

在你的Node脚本开头添加：

process.env.DISPLAY = ':0';

4. 配置Puppeteer强制全屏启动 #

在Puppeteer的启动参数中添加全屏及无桌面兼容参数：

const browser = await puppeteer.launch({
  headless: false,
  args: [
    '--start-fullscreen', // 强制全屏启动Chrome
    '--no-sandbox', // 无桌面环境下Chrome运行必需参数
    '--disable-dev-shm-usage', // 解决无桌面环境内存限制问题
    '--display=:0' // 再次绑定DISPLAY，确保生效
  ]
});

5. 验证配置 #

• 重启服务器：reboot
• 检查X服务状态：systemctl status x-server.service，确保服务处于active (running)状态
• 检查PM2进程：pm2 status，确认Worker进程正常运行
• 查看HDMI屏幕，确认Chrome页面全屏显示且无错误

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