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)开源软件。
|