Gatsby 5.13.2搭配gatsby-plugin-preact构建报错：renderToPipeableStream不是函数

问题 #

使用Gatsby 5.13.2版本，已安装gatsby-plugin-preact、preact及preact-render-to-string依赖，执行npm run build时出现如下错误：

WebpackError: TypeError: renderToPipeableStream is not a function

仅使用React时项目构建完全正常，当前package.json配置如下：

"dependencies": {
    "@rmwc/menu": "^14.0.7",
    "@rmwc/tabs": "^14.0.7",
    "classnames": "2.5.1",
    "common": "file:../common/",
    "dotenv": "8.2.0",
    "echarts": "^5.4.3",
    "echarts-for-react": "^3.0.2",
    "gatsby": "^5.13.2",
    "gatsby-plugin-env-variables": "^2.3.0",
    "gatsby-plugin-google-tagmanager": "^5.13.1",
    "gatsby-plugin-image": "^3.13.1",
    "gatsby-plugin-manifest": "^5.13.1",
    "gatsby-plugin-optimize-svgs": "^1.0.5",
    "gatsby-plugin-preact": "^7.13.1",
    "gatsby-plugin-react-helmet": "^6.13.1",
    "gatsby-plugin-react-helmet-canonical-urls": "^1.4.0",
    "gatsby-plugin-react-svg": "^3.3.0",
    "gatsby-plugin-recaptcha": "^1.0.5",
    "gatsby-plugin-remove-trailing-slashes": "^4.19.0",
    "gatsby-plugin-robots-txt": "^1.8.0",
    "gatsby-plugin-s3": "^0.4.1",
    "gatsby-plugin-sass": "^6.13.1",
    "gatsby-plugin-sharp": "^5.13.1",
    "gatsby-plugin-sitemap": "^6.11.0",
    "gatsby-plugin-split-css": "^2.0.3",
    "gatsby-plugin-webpack-bundle-analyser-v2": "^1.1.32",
    "gatsby-source-drupal": "^6.13.1",
    "gatsby-source-filesystem": "^5.13.1",
    "gatsby-transformer-sharp": "^5.13.1",
    "parse-entities": "4.0.1",
    "preact": "^10.19.6",
    "preact-render-to-string": "^5.2.6",
    "react": "^18.2.0",
    "react-compare-slider": "3.0.1",
    "react-dom": "^18.2.0",
    "react-helmet": "6.1.0",
    "react-html-parser": "2.0.2",
    "react-infinite-scroller": "1.2.6",
    "react-modal": "3.16.1",
    "react-player": "^2.14.1",
    "react-scroll": "1.9.0",
    "react-share": "5.0.3",
    "react-zoom-pan-pinch": "^3.3.0",
    "sass": "^1.70.0",
    "swiper": "6.5.4",
    "typed.js": "^2.1.0",
    "universal-cookie": "4.0.4",
    "uuid": "^9.0.1"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^6.3.0",
    "@types/jest": "^29.5.11",
    "@types/node": "^20.11.7",
    "@types/react": "^18.2.48",
    "@types/react-dom": "^18.2.18",
    "@types/react-helmet": "^6.1.11",
    "@types/react-html-parser": "2.0.6",
    "@types/react-infinite-scroller": "1.2.5",
    "@types/react-scroll": "1.8.10",
    "@types/uuid": "^9.0.8",
    "gatsby-plugin-typescript-checker": "1.1.1",
    "jest": "^29.7.0",
    "tsc-files": "^1.1.4",
    "typescript": "5.3.3"
  }

解决方案 #

问题根源 #

Gatsby 5+ 默认启用React 18的流式渲染API renderToPipeableStream，但Preact目前未实现该API，preact-render-to-string仅提供renderToString、renderToStaticMarkup这类同步渲染方法，导致构建时调用不存在的函数报错。

修复步骤 #

1. 调整插件加载顺序
   在gatsby-config.js中确保gatsby-plugin-preact是第一个加载的插件，保证它优先替换React相关导入：

module.exports = {
  plugins: [
    `gatsby-plugin-preact`,
    // 其他所有插件放在后面
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    // ...
  ]
}

2. 强制禁用流式渲染
   在gatsby-config.js中添加flags配置，关闭Gatsby的流式渲染功能：

module.exports = {
  flags: {
    RENDER_TO_PIPEABLE_STREAM: false
  },
  plugins: [
    // ...你的插件列表
  ]
}

3. 手动配置Webpack别名
   如果上述方法无效，在gatsby-node.js中添加Webpack别名，确保所有React导入都指向Preact：

exports.onCreateWebpackConfig = ({ actions }) => {
  actions.setWebpackConfig({
    resolve: {
      alias: {
        'react': 'preact/compat',
        'react-dom': 'preact/compat',
        'react-dom/server': 'preact-render-to-string'
      }
    }
  })
}

4. 重新安装依赖
   删除现有依赖缓存后重新安装，确保版本兼容：

rm -rf node_modules package-lock.json
npm install

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