Next.js SSR项目导入Puppeteer时报the "original" argument must be of type Function错误

开发者阿泽

2026-10-5

报错根因

该错误由Next.js的webpack打包逻辑触发：Puppeteer是纯服务端Node工具，依赖大量Node原生API，一旦被webpack打包到客户端侧bundle，依赖的util.promisify等Node原生方法的浏览器polyfill不兼容其内部依赖extract-zip的调用逻辑，就会抛出类型错误。

解决方案

确保Puppeteer逻辑仅在服务端运行
把所有调用Puppeteer的代码放到getServerSideProps、getStaticProps、pages/api目录下的服务端接口中，这部分代码不会被打包到客户端bundle，不会触发浏览器侧依赖兼容问题。

修改Next.js配置排除Puppeteer打包
在项目根目录的next.config.js中添加如下配置，避免webpack打包Puppeteer及其相关依赖：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      // 客户端侧忽略Node原生API依赖
      config.resolve.fallback = {
        ...config.resolve.fallback,
        fs: false,
        net: false,
        tls: false,
        child_process: false,
      }
    } else {
      // 服务端直接调用node_modules中的Puppeteer包，不打包
      config.externals = [...config.externals, 'puppeteer']
    }
    return config
  },
}

module.exports = nextConfig

安装适配Node14的Puppeteer版本
Puppeteer v20及以上版本最低要求Node16，Node14环境最高兼容v19.x版本，可卸载现有版本后安装适配版：
```
npm uninstall puppeteer && npm install puppeteer@19
```
优化HTML解析场景的调用逻辑
仅需要解析修改HTML的场景下，可改用puppeteer-core搭配本地已安装的Chrome/Chromium，无需Puppeteer自动下载浏览器二进制文件，进一步减少依赖加载冲突。