Playwright Docker容器报错browser.newPage() is not a function的原因排查

问题场景 #

在Playwright Docker容器环境中执行代码时，触发browser.newPage() is not a function报错，相关代码如下：

async function launchBrowser() {
    console.log("Launching Browser")
    try {
        let browser = await chromium.launch({
            args: [
                "--disable-web-security",
                "--use-fake-ui-for-media-stream",
                "--use-fake-device-for-media-stream",
                "--allow-file-access",
                "--disable-gpu",
                "--incognito",
                "--mute-audio",
                "--disable-dev-shm-usage"
            ],
            headless: localIsHeadless,
            slowMo: 100,
            timeout: 60000
        });

        return browser;
    } catch (err) {
        return err;
    }

}

async function newPage(browser, url) {
    console.log("New Page")
    const page = await browser.newPage();

    console.log("Setting Viewport")
    await page.setViewportSize({
        width: 1440,
        height: 900,
    });

    console.log("Granting Permissions")
    await page.context().grantPermissions(['camera', 'microphone']);

    console.log("Go to url : " + url)
    await page.goto(url);

    return page;
}

排查与解决步骤 #

1. 错误根源定位：launchBrowser的try/catch块捕获到浏览器启动错误后，直接返回了错误对象而非预期的Browser实例。后续调用newPage时，传入的browser是错误对象，自然不存在newPage()方法，引发报错。
2. 启动失败原因：移除try/catch后，明确看到错误提示——Docker容器无图形界面，不支持以headful模式启动浏览器。
3. 解决方法：将headless参数设置为true，以headless模式启动浏览器，重新运行代码后问题解决。

额外提示 #

• Docker环境下必须使用headless模式运行Playwright浏览器，否则会因缺少图形驱动导致启动失败。
• 优化错误处理逻辑：不要直接返回错误对象，应抛出错误或给出明确提示，避免调用方混淆返回值类型。

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