245 lines
5.8 KiB
Markdown
245 lines
5.8 KiB
Markdown
# React性能扫描工具
|
||
|
||
`React` `性能优化` `开发工具` `渲染检测`
|
||
|
||
# React Scan
|
||
|
||
React Scan 自动检测 React 应用中的性能问题。
|
||
|
||
- 无需修改代码 —— 直接接入即可
|
||
- 精确高亮需要优化的组件
|
||
- 通过页面上的工具栏随时访问
|
||
|
||
### 快速开始
|
||
|
||
```bash
|
||
npx -y react-scan@latest init
|
||
```
|
||
|
||
### [**试试演示！→**](https://react-scan.million.dev)
|
||
|
||
<img
|
||
src="https://github.com/user-attachments/assets/c21b3afd-c7e8-458a-a760-9a027be7dc02"
|
||
alt="React Scan 运行效果"
|
||
width="600"
|
||
/>
|
||
|
||
## 安装
|
||
|
||
`init` 命令会自动检测你的框架，通过 npm 安装 `react-scan`，并完成项目配置。
|
||
|
||
```bash
|
||
npx -y react-scan@latest init
|
||
```
|
||
|
||
### 手动安装
|
||
|
||
安装依赖包：
|
||
|
||
```bash
|
||
npm install -D react-scan
|
||
```
|
||
|
||
然后在应用中添加 script 标签。根据你的框架选择对应指南：
|
||
|
||
#### Script 标签
|
||
|
||
在 `index.html` 中所有脚本之前粘贴以下内容：
|
||
|
||
```html
|
||
<!-- 粘贴到所有脚本之前 -->
|
||
<script
|
||
crossOrigin="anonymous"
|
||
src="//unpkg.com/react-scan/dist/auto.global.js"
|
||
></script>
|
||
```
|
||
|
||
#### Next.js（App Router）
|
||
|
||
在 `app/layout.tsx` 中添加：
|
||
|
||
```tsx
|
||
import Script from "next/script";
|
||
|
||
export default function RootLayout({ children }) {
|
||
return (
|
||
<html>
|
||
<head>
|
||
<Script
|
||
src="//unpkg.com/react-scan/dist/auto.global.js"
|
||
crossOrigin="anonymous"
|
||
strategy="beforeInteractive"
|
||
/>
|
||
</head>
|
||
<body>{children}</body>
|
||
</html>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Next.js（Pages Router）
|
||
|
||
在 `pages/_document.tsx` 中添加：
|
||
|
||
```tsx
|
||
import { Html, Head, Main, NextScript } from "next/document";
|
||
import Script from "next/script";
|
||
|
||
export default function Document() {
|
||
return (
|
||
<Html lang="en">
|
||
<Head>
|
||
<Script
|
||
src="//unpkg.com/react-scan/dist/auto.global.js"
|
||
crossOrigin="anonymous"
|
||
strategy="beforeInteractive"
|
||
/>
|
||
</Head>
|
||
<body>
|
||
<Main />
|
||
<NextScript />
|
||
</body>
|
||
</Html>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Vite
|
||
|
||
启用 React Scan 的 `index.html` 示例：
|
||
|
||
```html
|
||
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<script
|
||
crossOrigin="anonymous"
|
||
src="//unpkg.com/react-scan/dist/auto.global.js"
|
||
></script>
|
||
</head>
|
||
<body>
|
||
<div id="root"></div>
|
||
<script type="module" src="/src/main.tsx"></script>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
#### Remix
|
||
|
||
在 `app/root.tsx` 中添加：
|
||
|
||
```tsx
|
||
import { Links, Meta, Outlet, Scripts } from "@remix-run/react";
|
||
|
||
export default function App() {
|
||
return (
|
||
<html>
|
||
<head>
|
||
<Meta />
|
||
<script
|
||
crossOrigin="anonymous"
|
||
src="//unpkg.com/react-scan/dist/auto.global.js"
|
||
/>
|
||
<Links />
|
||
</head>
|
||
<body>
|
||
<Outlet />
|
||
<Scripts />
|
||
</body>
|
||
</html>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 浏览器扩展
|
||
|
||
按照[此处](https://github.com/aidenybai/react-scan/blob/main/BROWSER_EXTENSION_GUIDE.md)的指南安装扩展。
|
||
|
||
## API 参考
|
||
|
||
<details>
|
||
<summary><code>Options（配置项）</code></summary>
|
||
|
||
<br />
|
||
|
||
```tsx
|
||
export interface Options {
|
||
/**
|
||
* 启用/禁用扫描
|
||
* @default true
|
||
*/
|
||
enabled?: boolean;
|
||
|
||
/**
|
||
* 强制 React Scan 在生产环境运行（不推荐）
|
||
* @default false
|
||
*/
|
||
dangerouslyForceRunInProduction?: boolean;
|
||
|
||
/**
|
||
* 将渲染日志输出到控制台
|
||
* @default false
|
||
*/
|
||
log?: boolean;
|
||
|
||
/**
|
||
* 显示工具栏
|
||
* @default true
|
||
*/
|
||
showToolbar?: boolean;
|
||
|
||
/**
|
||
* 动画速度
|
||
* @default "fast"
|
||
*/
|
||
animationSpeed?: "slow" | "fast" | "off";
|
||
|
||
onCommitStart?: () => void;
|
||
onRender?: (fiber: Fiber, renders: Array<Render>) => void;
|
||
onCommitFinish?: () => void;
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
- `scan(options: Options)`：启动扫描的命令式 API
|
||
- `useScan(options: Options)`：启动扫描的 Hook API
|
||
- `setOptions(options: Options): void`：运行时动态设置配置项
|
||
- `getOptions()`：获取当前配置项
|
||
- `onRender(Component, onRender: (fiber: Fiber, render: Render) => void)`：监听特定组件的渲染事件
|
||
|
||
## 为什么选择 React Scan？
|
||
|
||
React 的性能优化往往并不直观。
|
||
|
||
问题在于组件 props 是按引用比较而非按值比较。这是有意为之的 —— 渲染本身的开销通常很低。
|
||
|
||
然而，这也很容易意外触发不必要的重渲染，导致应用变慢。即使是拥有数百名工程师的生产级应用也无法完全避免这个问题（参见 [GitHub](https://github.com/aidenybai/react-scan/blob/main/.github/assets/github.mp4)、[Twitter](https://github.com/aidenybai/react-scan/blob/main/.github/assets/twitter.mp4) 和 [Instagram](https://github.com/aidenybai/react-scan/blob/main/.github/assets/instagram.mp4) 的示例）。
|
||
|
||
```jsx
|
||
<ExpensiveComponent onClick={() => alert("hi")} style={{ color: "purple" }} />
|
||
```
|
||
|
||
React Scan 通过自动检测并高亮导致性能问题的渲染，帮助你识别这类问题。
|
||
|
||
## 资源与贡献
|
||
|
||
想试试看？查看[演示](https://react-scan.million.dev)。
|
||
|
||
想要贡献代码？查看[贡献指南](https://github.com/aidenybai/react-scan/blob/main/CONTRIBUTING.md)。
|
||
|
||
想和社区交流？加入我们的 [Discord](https://discord.gg/X9yFbcV2rF)。
|
||
|
||
发现了 Bug？前往我们的[问题追踪器](https://github.com/aidenybai/react-scan/issues)。
|
||
|
||
[**→ 在 GitHub 上开始贡献**](https://github.com/aidenybai/react-scan/blob/main/CONTRIBUTING.md)
|
||
|
||
## 致谢
|
||
|
||
- [React Devtools](https://react.dev/learn/react-developer-tools) —— 高亮渲染的最初灵感来源
|
||
- [Million Lint](https://million.dev) —— 扫描与 lint 方案的参考
|
||
- [Why Did You Render?](https://github.com/welldone-software/why-did-you-render) —— 检测不必要渲染的概念参考
|
||
|
||
## 许可证
|
||
|
||
React Scan 是由 Aiden Bai、[Million Software, Inc.](https://million.dev) 及[贡献者们](https://github.com/aidenybai/react-scan/graphs/contributors)开发的 [MIT 许可证](LICENSE)开源软件。 |