Gatsby 5+集成gatsby-plugin-preact失败，寻求解决方案

使用Gatsby 5.13.2，已安装gatsby-plugin-preact、preact和preact-render-to-string，开发模式打开首页时出现以下错误：

{
"codeFrame": "No codeFrame could be generated",
"sourcePosition": null,
"sourceContent": null
}

控制台提示：

warn The path "/" errored during SSR.

页面已简化为最简代码仍报错：

import React from 'react';
import './homepage.scss';

const HomePage = () => <div>Test</div>;

export default function HomePageLanding(): React.ReactElement {
  return <HomePage />;
}

不使用Preact时项目运行完全正常，求解决方法。

1. 调整插件加载顺序 #

确保gatsby-plugin-preact在gatsby-config.js的plugins数组中排在最顶部，让它优先完成React到Preact的替换，避免其他插件提前加载React相关代码：

module.exports = {
  plugins: [
    'gatsby-plugin-preact', // 必须放在最前面
    // 其他插件按原有顺序排列
    'gatsby-plugin-react-helmet',
    'gatsby-plugin-image',
    // ...
  ]
}

2. 清理冗余依赖 #

既然用Preact替代React，建议移除react、react-dom依赖，避免版本冲突或冗余加载：

# npm
npm uninstall react react-dom

# yarn
yarn remove react react-dom

3. 配置TypeScript路径别名（TS项目专属） #

在tsconfig.json中添加路径映射，让TypeScript识别Preact作为React的替代：

{
  "compilerOptions": {
    "paths": {
      "react": ["./node_modules/preact/compat"],
      "react-dom": ["./node_modules/preact/compat"]
    }
  }
}

4. 清除Gatsby缓存后重启 #

缓存可能残留旧的React编译文件，执行以下命令彻底清理后重启：

gatsby clean
gatsby develop

5. 重新安装依赖确保版本兼容 #

删除现有依赖文件后重新安装，避免依赖版本不匹配问题：

# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

6. 排查第三方库兼容性 #

部分React生态库可能不完全兼容Preact（如react-helmet、react-html-parser），可以暂时注释相关插件测试：

• 先禁用gatsby-plugin-react-helmet和gatsby-plugin-react-helmet-canonical-urls
• 如果问题消失，替换为Preact兼容的替代方案（比如@preact/helmet）

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