Azure Linux部署whatsapp-web.js报puppeteer启动浏览器失败

报错核心是Puppeteer捆绑的Chromium浏览器在Azure Linux环境启动失败，缺少libgobject-2.0.so.0等系统级运行依赖。本地桌面系统（Windows/macOS/带桌面的Linux）默认预装了这类GUI程序依赖库，所以本地运行正常，纯服务器版Linux默认不带这些组件，直接跑就会报共享库缺失错误。

1. 安装Chromium运行依赖 #

首先连接到你的Azure Linux实例，如果你用的是Azure默认提供的Ubuntu/Debian系镜像，直接执行以下命令安装所有必需依赖：

sudo apt update
sudo apt install -y libgobject-2.0-0 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libasound2 libpangocairo-1.0-0 libxshmfence1

嫌逐个找依赖麻烦的话，可以直接安装系统源里的Chromium包，会自动拉取所有关联依赖，稳定性更好：

sudo apt install -y chromium-browser

2. 修改WhatsApp Web.js启动配置 #

安装完系统Chromium后，修改客户端初始化代码，指定使用系统Chromium路径，同时添加Linux服务器环境必需的启动参数：

const { Client } = require('whatsapp-web.js');
const client = new Client({
  puppeteer: {
    executablePath: '/usr/bin/chromium-browser',
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage'
    ]
  }
});

注意：root用户下运行Chromium必须加--no-sandbox参数，否则会触发沙箱权限报错；--disable-dev-shm-usage用来规避Linux默认/dev/shm空间不足导致的崩溃问题。

3. 容器化部署适配 #

如果你是用自定义Docker容器部署到Azure，直接在Dockerfile里加入依赖安装步骤即可，不需要手动进实例操作：

FROM node:16-bullseye
RUN apt update && apt install -y chromium-browser --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*
# 后续保留原有的工作目录创建、代码拷贝、npm依赖安装、服务启动逻辑即可

如果安装完上述依赖后仍报其他.so文件缺失，执行以下命令可以一次性列出所有缺失的共享库，直接对应安装即可：

ldd ./node_modules/whatsapp-web.js/node_modules/puppeteer/.local-chromium/linux-*/chrome-linux/chrome | grep "not found"

你当前使用的Node 16+、whatsapp-web.js 1.15.8、Puppeteer 12.0.1版本组合没有兼容性问题，不需要额外降级或升级版本。

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