aidenybai--react-scan
wehub-resource-sync
247 行
6.3 KiB
Markdown
247 行
6.3 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/aidenybai/react-scan) · [上游 README](https://github.com/aidenybai/react-scan/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# <img src="https://github.com/aidenybai/react-scan/blob/main/.github/assets/logo.svg" width="30" height="30" align="center" /> 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
|
||
<!-- paste this BEFORE any scripts -->
|
||
<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 {
|
||
/**
|
||
* Enable/disable scanning
|
||
* @default true
|
||
*/
|
||
enabled?: boolean;
|
||
|
||
/**
|
||
* Force React Scan to run in production (not recommended)
|
||
* @default false
|
||
*/
|
||
dangerouslyForceRunInProduction?: boolean;
|
||
|
||
/**
|
||
* Log renders to the console
|
||
* @default false
|
||
*/
|
||
log?: boolean;
|
||
|
||
/**
|
||
* Show toolbar bar
|
||
* @default true
|
||
*/
|
||
showToolbar?: boolean;
|
||
|
||
/**
|
||
* Animation speed
|
||
* @default "fast"
|
||
*/
|
||
animationSpeed?: "slow" | "fast" | "off";
|
||
|
||
onCommitStart?: () => void;
|
||
onRender?: (fiber: Fiber, renders: Array<Render>) => void;
|
||
onCommitFinish?: () => void;
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
- `scan(options: Options)`：用于启动扫描的命令式 API（Imperative API）
|
||
- `useScan(options: Options)`：用于启动扫描的 Hook API
|
||
- `setOptions(options: Options): void`：在运行时设置选项
|
||
- `getOptions()`：获取当前选项
|
||
- `onRender(Component, onRender: (fiber: Fiber, render: Render) => void)`：接入特定组件的渲染
|
||
|
||
## 为什么选择 React Scan？
|
||
|
||
React 优化可能很棘手。
|
||
|
||
问题在于组件 props 是按引用（reference）而非值（value）进行比较的。这是有意为之 —— 渲染本身的执行成本可以很低。
|
||
|
||
然而，这也容易意外引发不必要的渲染，从而让应用变慢。即使是拥有数百名工程师的生产级应用，也无法完全优化（参见 [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-licensed](LICENSE) 开源软件。
|