基于azure-functions/node:4-node14-slim的Docker容器中运行Puppeteer启动失败问题排查及可行配置方案

嘿，我刚仔细梳理了你的问题，这个Docker容器启动失败的坑我之前也踩过，来帮你拆解下原因，再分享验证可行的解决方案：

问题到底出在哪？ #

你看到的Missing X server or $DISPLAY错误，核心原因是Chrome默认会尝试启动图形界面，但Docker容器里没有X11服务环境。除此之外，你的初始Dockerfile还有几个致命的逻辑问题：

• 错误覆盖了容器的启动命令：你设置的ENTRYPOINT和CMD会让容器启动后直接跑Chrome，而不是Azure Function Host，这完全背离了Function App的运行逻辑；
• 不必要的用户权限配置：虽然创建非特权用户是最佳实践，但你的配置把大量目录权限变更，反而可能导致Function Host无法正常访问代码目录，而且没配合正确的Puppeteer启动参数；
• Puppeteer启动参数缺失：即使装了Chrome，没指定无头模式和沙箱禁用参数，Chrome还是会触发图形界面依赖的报错。

修正后的可行配置 #

我帮你整理了经过验证的配置，分Dockerfile和Puppeteer代码两部分：

调整后的Dockerfile #

FROM mcr.microsoft.com/azure-functions/node:4-node14-slim
#####################
#PUPPETEER 环境配置
#####################
# 安装Chrome及多语言字体，确保Puppeteer能正常渲染各种字符
RUN apt-get update && apt-get -f install && apt-get -y install wget gnupg2 apt-utils
RUN wget --no-verbose -O /tmp/chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb \
 && apt-get update \
 && apt-get install -y /tmp/chrome.deb --no-install-recommends --allow-downgrades fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf \
 && rm /tmp/chrome.deb
#####################
#PUPPETEER 配置结束
#####################
# 指定Puppeteer使用系统安装的Chrome，避免重复下载Chromium浪费空间
ENV PUPPETEER_EXECUTABLE_PATH "/usr/bin/google-chrome-stable"
# Azure Function 必备环境变量
ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
    AzureFunctionsJobHost__Logging__Console__IsEnabled=true
# 复制代码到Function App的默认目录并安装依赖
COPY . /home/site/wwwroot
WORKDIR /home/site/wwwroot
RUN npm install

小提示：

• 去掉了多余的ENTRYPOINT和CMD，因为Azure Function的基础镜像已经自带了启动Function Host的命令，不需要额外覆盖；
• 直接用系统安装的Chrome，通过环境变量指定路径，避免Puppeteer重复下载Chromium，大幅减小镜像体积；
• 简化了依赖安装步骤，确保字体齐全，支持中文、日文等多语言页面渲染。

修正后的Puppeteer启动代码 #

const url = req.query.url || "https://google.com/";
const browser = await puppeteer.launch({
  executablePath: process.env.PUPPETEER_EXECUTABLE_PATH, // 和Docker里的环境变量对应
  args: [
    '--no-sandbox', 
    '--disable-setuid-sandbox',
    '--headless=new', // 无头模式，彻底不需要图形界面
    '--disable-gpu', // 容器环境不需要GPU加速
    '--disable-dev-shm-usage' // 解决容器中共享内存不足的常见问题
  ],
});
const page = await browser.newPage();
await page.goto(url);
const screenshotBuffer = await page.screenshot({ fullPage: true });
await browser.close();
context.res = {
  body: screenshotBuffer,
  headers: { "content-type": "image/png" }
};

小提示：

• 明确指定executablePath，确保Puppeteer用我们安装的Chrome，而不是自带的Chromium；
• --headless=new是Puppeteer v14+推荐的无头模式参数，完美规避X server依赖；
• --disable-dev-shm-usage可以解决容器中共享内存不足导致Chrome崩溃的问题。

验证启动 #

用你原来的命令启动容器就行：

docker run -i --init --rm --cap-add=SYS_ADMIN -p 7071:80 pdfgen:dev

启动后访问http://localhost:7071/api/你的函数名称?url=https://example.com，就能正常生成截图啦！

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