> [!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 文件为准。
# 
React Scan
React Scan 会自动检测 React 应用中的性能问题。
- 无需修改代码 —— 只需引入即可
- 精确高亮你需要优化的组件
- 通过页面工具栏随时可用
### 快速开始
```bash
npx -y react-scan@latest init
```
### [**试用演示！→**](https://react-scan.million.dev)
## 安装
`init` 命令会自动检测你的框架，通过 npm 安装 `react-scan`，并完成项目配置。
```bash
npx -y react-scan@latest init
```
### 手动安装
安装该包：
```bash
npm install -D react-scan
```
然后将 script 标签添加到你的应用中。请选择适用于你框架的指南：
#### Script 标签
在任何脚本之前，将以下内容粘贴到你的 `index.html` 中：
```html
```
#### Next.js (App Router)
将以下内容添加到你的 `app/layout.tsx` 中：
```tsx
import Script from "next/script";
export default function RootLayout({ children }) {
return (
{children}
);
}
```
#### 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 (
);
}
```
#### Vite
启用 React Scan 的 `index.html` 示例：
```html
```
#### Remix
将以下内容添加到你的 `app/root.tsx` 中：
```tsx
import { Links, Meta, Outlet, Scripts } from "@remix-run/react";
export default function App() {
return (
);
}
```
### 浏览器扩展
按照[此处](https://github.com/aidenybai/react-scan/blob/main/BROWSER_EXTENSION_GUIDE.md). 的指南安装扩展。
## API 参考
Options
```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) => void;
onCommitFinish?: () => void;
}
```
- `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
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) 开源软件。