在Rsbuild项目中集成React-Scan的实践指南

React-Scan是一个用于React应用性能分析和调试的工具，本文将详细介绍如何在基于Rsbuild的项目中正确集成和使用React-Scan。

两种集成方案

方案一：通过HTML标签引入

在Rsbuild配置文件中，可以通过修改html.tags配置项来直接引入React-Scan的CDN脚本：

export default {
  html: {
    tags: [
      { 
        tag: 'script', 
        attrs: { 
          src: 'https://unpkg.com/react-scan/dist/auto.global.js' 
        } 
      },
    ],
  },
};

这种方式的优点是简单直接，不需要额外的构建配置，适合快速集成。缺点是依赖外部CDN，可能会受到网络环境的影响。

方案二：通过NPM包引入

另一种方式是通过NPM安装React-Scan：

npm install react-scan

然后在应用入口文件中导入并使用：

import { scan } from 'react-scan';

scan({
  enabled: true,
  log: true,
});

需要注意的是，导入语句必须放在React导入之前，否则可能无法正常工作。

自定义Rsbuild插件方案

如果上述两种标准方式不能满足需求，还可以创建一个自定义Rsbuild插件来实现更灵活的集成：

import type { RsbuildPlugin } from '@rsbuild/core';
import { scan } from 'react-scan';

type ScanOptions = Parameters<typeof scan>[0];

export const reactScanPlugin = (options: ScanOptions = { 
  log: true, 
  enabled: true 
}): RsbuildPlugin => ({
  name: 'react-scan-plugin',
  setup(api) {
    api.modifyWebpackChain((chain) => {
      chain.entry('index')
        .prepend(`scan(${JSON.stringify(options)});`)
        .end();
    });
  },
});

这个插件会在Webpack构建过程中，自动将scan调用插入到入口文件的最前面，确保它在React之前执行。

最佳实践建议

1. 对于大多数项目，推荐使用HTML标签引入的方式，简单可靠
2. 如果需要自定义配置项，可以考虑使用NPM包方式
3. 只有在有特殊需求时才考虑自定义插件方案
4. 无论采用哪种方式，都要确保scan在React之前执行
5. 生产环境建议关闭scan的日志输出以减少性能开销

通过以上方法，开发者可以轻松地在Rsbuild项目中集成React-Scan，获得应用性能分析的强大能力。