Docker环境下Headless Chrome无法渲染文本问题求助

我开发了一个基于Python和html2image框架、利用Chrome生成图片的机器人，该程序在本地及VPS上运行正常，但在Docker环境中无法渲染文本。

Chrome初始化代码 #

hti = Html2Image(
    size=(781, 4000),
    custom_flags=[
        "--disable-gpu",
        "--no-sandbox",
        "--disable-setuid-sandbox",
        "--headless=new",
        "--hide-scrollbars",
        "--log-level=3",
    ],
)

...

hti.screenshot(html_str=html, css_str=css, save_as=name)

字体CSS配置片段 #

@font-face {
    font-family: "Noto Sans";
    src: url("$fontregular");
}

@font-face {
    font-family: "Noto Emoji";
    src: url("$fontemoji");
}

@font-face {
    font-family: "Noto Mono";
    src: url("$fontmono");
}

$vars会在运行时通过Python的Template替换为完整字体路径，我认为这并非字体问题，否则文本会以默认字体渲染。

Dockerfile #

FROM debian:bookworm-slim@sha256:6bdbd579ba71f6855deecf57e64524921aed6b97ff1e5195436f244d2cb42b12 as chrome

RUN sed -i 's/deb.debian.org/debian.anexia.at/g' /etc/apt/sources.list.d/debian.sources
RUN apt-get update && apt-get install -y wget gnupg
RUN wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -
RUN echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list
RUN apt-get install -f -y curl fonts-liberation libasound2 libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0
RUN apt-get install -f -y libcairo2 libcups2 libdbus-1-3 libdrm2 libexpat1 libgbm1 libglib2.0-0 libgtk-3-0 libgtk-4-1
RUN apt-get install -f -y libpango-1.0-0 libu2f-udev libvulkan1 libx11-6 libxcb1 libxcomposite1 libxdamage1 libxext6
RUN apt-get install -f -y libxkbcommon0 libxrandr2 xdg-utils libglib2.0-dev libnspr4 libnss3 libxfixes3 libc-bin libc6
RUN apt-get install -f -y locales
RUN curl -O https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
RUN dpkg -i google-chrome-stable_current_amd64.deb

FROM bitnami/python:3.9.18-debian-12-r29@sha256:607688045123fb4d60d6894ab64f297e51624883b51c340da1842dc5c8585411

COPY --from=chrome /opt/google/chrome /opt/google/chrome
COPY --from=chrome /usr/lib/x86_64-linux-gnu /usr/lib/x86_64-linux-gnu
COPY --from=chrome /etc/fonts /etc/fonts

RUN echo "export PATH=/opt/google/chrome:${PATH}" >> /root/.bashrc

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY bot ./bot
COPY files ./files
COPY main.py .

CMD ["python", "main.py"]

Chrome运行日志 #

bot-1  | [0228/135225.424577:WARNING:chrome_main_linux.cc(80)] Read channel stable from /opt/google/chrome/CHROME_VERSION_EXTRA
bot-1  | [0228/135225.449320:WARNING:chrome_main_linux.cc(80)] Read channel stable from /opt/google/chrome/CHROME_VERSION_EXTRA
bot-1  | [9:9:0228/135225.473287:ERROR:browser_dm_token_storage_linux.cc(100)] Error: /etc/machine-id contains 0 characters (32 were expected).
bot-1  | (process:9): GLib-GIO-CRITICAL **: 13:52:25.699: g_settings_schema_source_lookup: assertion 'source != NULL' failed
bot-1  | [0228/135226.330480:ERROR:file_io_posix.cc(145)] open /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq: No such file or directory (2)
bot-1  | [0228/135226.330512:ERROR:file_io_posix.cc(145)] open /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq: No such file or directory (2)
bot-1  | [167:167:0228/135226.308521:ERROR:check.cc(319)] Check failed: false. NOTREACHED log messages are omitted in official builds. Sorry!
bot-1  | [167:167:0228/135226.332990:ERROR:check.cc(319)] Check failed: false. NOTREACHED log messages are omitted in official builds. Sorry!

渲染效果对比 #

• 预期：完整展示所有文本内容
• 实际：文本完全缺失，仅保留非文本元素

问题排查与解决方案 #

1. 修复/etc/machine-id缺失问题 #

日志显示/etc/machine-id为空，Chrome依赖该文件完成初始化，在Dockerfile的final阶段添加：

RUN dbus-uuidgen > /etc/machine-id

2. 补充字体渲染依赖 #

Docker镜像可能缺少基础字体和渲染组件，在final阶段安装：

RUN apt-get update && apt-get install -y --no-install-recommends \
    fonts-noto fonts-noto-cjk fonts-noto-emoji \
    libpango1.0-0 libpangocairo-1.0-0 \
    && rm -rf /var/lib/apt/lists/*

3. 调整Chrome启动参数 #

添加参数避免共享内存限制和渲染异常：

hti = Html2Image(
    size=(781, 4000),
    custom_flags=[
        "--disable-gpu",
        "--no-sandbox",
        "--disable-setuid-sandbox",
        "--headless=new",
        "--hide-scrollbars",
        "--log-level=3",
        "--font-render-hinting=none",
        "--disable-dev-shm-usage",
    ],
)

4. 验证字体路径正确性 #

在容器内执行命令检查字体文件是否存在：

ls -l /path/to/your/fonts/

同时在代码中打印替换后的CSS内容，确认路径无误。

5. 简化Docker镜像构建 #

避免复制整个/usr/lib/x86_64-linux-gnu导致依赖冲突，直接在final阶段安装Chrome及依赖：

FROM bitnami/python:3.9.18-debian-12-r29@sha256:607688045123fb4d60d6894ab64f297e51624883b51c340da1842dc5c8585411

RUN apt-get update && apt-get install -y --no-install-recommends \
    wget gnupg curl fonts-liberation libasound2 libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 \
    libcairo2 libcups2 libdbus-1-3 libdrm2 libexpat1 libgbm1 libglib2.0-0 libgtk-3-0 libgtk-4-1 \
    libpango-1.0-0 libu2f-udev libvulkan1 libx11-6 libxcb1 libxcomposite1 libxdamage1 libxext6 \
    libxkbcommon0 libxrandr2 xdg-utils libnspr4 libnss3 libxfixes3 locales \
    fonts-noto fonts-noto-cjk fonts-noto-emoji \
    && rm -rf /var/lib/apt/lists/*

RUN wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -
RUN echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list
RUN apt-get update && apt-get install -y google-chrome-stable \
    && rm -rf /var/lib/apt/lists/*

RUN dbus-uuidgen > /etc/machine-id
RUN echo "export PATH=/opt/google/chrome:${PATH}" >> /root/.bashrc

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY bot ./bot
COPY files ./files
COPY main.py .

CMD ["python", "main.py"]

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